NAV
shell

Conventions

The base URL to send all API requests is https://betaapi.audiohook.com/v2/companies/:companyUUID. HTTPS is required for all API requests.

The Audiohook API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE. Response bodies are encoded as JSON.

Authorization

The API uses token-based authentication. Users need to sign in to https://app.audiohook.com/login to get a valid JWT token, which is then passed to the API in the Authorization header.

Send the JWT token in the Authorization header of all your requests:

Authorization: Bearer $JWT_TOKEN

If a client id and client secret is being used, send a post request to /get-token to receive a JWT token that lasts 1 hour. This token can then be used in the Authorization header.

Authentication

Authenticate

Request example

curl -X POST https://betaapi.audiohook.com/v2/authenticate \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            {
        "name": "X-Request-Header",
        "value": "Header value"
      }
        ],
    "body": {
      "token": "zsZymXaVNJmOlaNfZVuZhltSqPMEy-YcDcdLf48tRFNJ"
      "type": "oauth"
    }
  }'

Response sample

200 OK

{
  "Message": "",
  "type": "success",
  "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy",
  "user": {
      "name": {
          "first_name": "",
          "middle_name": "",
          "last_name": ""
      },
      "user_id": "user-live-404decf62",
      "trusted_metadata": {},
      "untrusted_metadata": {},
      "emails": [
          {
              "email_id": "email-live-69c5f6ec",
              "email": "example@audiohook.com",
              "verified": true
          }
      ],
      "phone_numbers": [],
      "providers": [
          {
              "oauth_user_registration_id": "oauth-user-live-2af84c6d",
              "provider_subject": "111270745762620521806",
              "provider_type": "Google",
              "profile_picture_url": "https://lh3.googleusercontent.com/a/AAcHTtfTlhdB-fgIrFJtRR_p",
              "locale": ""
          }
      ],
      "webauthn_registrations": [],
      "biometric_registrations": [],
      "totps": [],
      "crypto_wallets": [],
      "password": null,
      "created_at": "2023-03-16T20:48:41+00:00",
      "status": "active"
  }
}

Returns the user data with the token

HTTP Request

POST /v2/authenticate

Query Parameters

Parameter Default Data Type Description
token true string Token generated by the third party service
type true string Indicate the login process utilized (oauth or magic_links)

Get token

Request example

curl -X POST https://betaapi.audiohook.com/stage/get-token \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            {
        "name": "X-Request-Header",
        "value": "Header value"
      }
        ],
    "body": {
      "client_id": "ac500bf0-2567-4ba6-9776-89c664203d99"
      "client_secret": "47e438d3-8b12-45ab-9017-732349dfe925"
    }
  }'

Response sample

200 OK

{
  "_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "bearer"
}

Returns a JWT token that has a TTL of 1 hour

HTTP Request

POST /stage/get-token

Query Parameters

Parameter Default Data Type Description
client_id None string The client id associated with a advertiser/agency
client_secret None string The client secret associated with a advertiser/agency

Creatives

List all creatives

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/creatives \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
    }'

Response sample

200 OK

{
  "Message": "",
  "type": "success",
  "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy",
  "Creatives": [
    {
      "id": 9999,
      "creative_name": "Example ad",
      "created": "2023-02-13 17:00:34.136373",
      "audio_set_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/9999/audioad.wav",
      "display_asset_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/9999/displayad.jpg",
      "click_through_url": "https://test.com",
      "advertiser_id": 123,
      "converted": true,
      "filename": "audioad.wav",
      "status": true,
      "start_flight_date": null,
      "end_flight_date": null,
      "tags": [],
      "events_enabled": false,
      "events": [],
      "duration_secs": "30.09",
      "campaigns": [],
      "errors": []
    },
    {
      "id": 99999,
      "creative_name": "Example ad 2",
      "created": "2023-02-13 16:58:35.602515",
      "audio_set_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/99999/audioad.wav",
      "display_asset_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/99999/displayad.jpg",
      "click_through_url": "https://test.com",
      "advertiser_id": 123,
      "converted": true,
      "filename": "audioad.wav",
      "status": true,
      "start_flight_date": null,
      "end_flight_date": null,
      "tags": [],
      "events_enabled": false,
      "events": [],
      "duration_secs": "30.09",
      "campaigns": [],
      "errors": []
    }
  ],
  "page": "0",
  "size": "10",
  "total_records": 2
}

Returns a list of all creatives for a company.

HTTP Request

GET /v2/companies/:companyUUID/creatives/:creative_id

Query Parameters

Parameter Default Data Type Description
page 0 integer The page of integrations to return.
size 30 integer The total number of integrations to be sent.
order_by section asc string Order the response based off a key
q None string Filter by name or file name

Get a creative

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/creatives/9999 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
    "id": 9999,
    "creative_name": "Example ad",
    "created": "2023-02-13 17:00:34.136373",
    "audio_set_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/9999/audioad.wav",
    "display_asset_url": "https://ah-advertiser-creatives.s3.amazonaws.com/1234-abcd-qwer-xcvb/creatives/9999/displayad.jpg",
    "click_through_url": "https://test.com",
    "advertiser_id": 123,
    "converted": true,
    "filename": "audioad.wav",
    "status": true,
    "start_flight_date": null,
    "end_flight_date": null,
    "tags": [],
    "events_enabled": false,
    "events": [],
    "duration_secs": "30.09",
    "campaigns": [],
    "errors": []
}

Returns a creative with the given id

HTTP Request

GET /v2/companies/:companyUUID/creatives/:creativeId

Disassociate a creative

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/creatives/9999 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{"Message": "Creative deleted."}

Disassociates the creative from every campaign its associated with

HTTP Request

DELETE /v2/companies/:companyUUID/creatives/:creativeId

Create a creative

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/creatives \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
            "creative_name": "Snarkys 30 sec Christmas spot",
            "advertiser_id": "1234-abcd-qwer-xcvb",
            "status": true,
          "filename": "my-great-audio-ad.wav",
            "tags": ["30 secs", "sarcastic", "testing", "young"],
            "start_flight_date": "2022-12-01",
            "end_flight_date": "2023-01-01",
            "events": [
                {
                    "Type": "Impressions",
                    "url": "https://facebook.com/pixel?campaign=1234556543321"
                }
            ],
            "companion_ad": {
                "click_through_url": "https://snarkyspizza.com/?campaign=32123456&reference=1234567654321
                "display_asset_filename": "eat-at-snarkys-christmas-spot.png"
            }
        }

    }'

Response sample

200 OK

{
    "creativeId": 9999,
    "s3_data": {
        "url": "https://ah-advertiser-creatives-input.s3.amazonaws.com/",
    "fields": {
      "key": "1234-abcd-qwer-xcvb/creatives/9999/audioad.mp3",
      "AWSAccessKeyId": "ASHJDUIASHIUDASHDUIASHdi",
      "policy": "eyJleHBpcmF0aW9uIjogIjIwMjMtMDItMTBUMDA6NDI6MDJaIiwgImNvbmRpdGlvbnMiOiBbeyJidWNrZXQiOiAiYWgtYWR2ZXJ0aXNlci1jcmVhdGl2ZXMtaW5wdXQifSwgeyJrZXkiOiAiZmU5NTMxMGUtNmY2Zi00YWFkLWFhZDYtYzE4YWE3ZDg0ZWM3L2NyZWF0aXZlcy80OTQxL2F1ZGlvYWQubXAzIn1dfQ==",
      "signature": "ejEoRYAWr7iRJKPaugKgsQul5UY="
    }
  },
    "s3_displayad": {
        "url": "https://ah-advertiser-creatives.s3.amazonaws.com/",
    "fields": {
      "key": "1234-abcd-qwer-xcvb/creatives/9999/displayad.jpg",
      "AWSAccessKeyId": "ASHJDUIASHIUDASHDUIASHdi",
      "policy": "eyJleHBpcmF0aW9uIjogIjIwMjMtMDItMTBUMDA6NDI6MDJaIiwgImNvbmRpdGlvbnMiOiBbeyJidWNrZXQiOiAiYWgtYWR2ZXJ0aXNlci1jcmVhdGl2ZXMifSwgeyJrZXkiOiAiZmU5NTMxMGUtNmY2Zi00YWFkLWFhZDYtYzE4YWE3ZDg0ZWM3L2NyZWF0aXZlcy80OTQxL2Rpc3BsYXlhZC5qcGcifV19",
      "signature": "4fzF10Dsu/bbDzNeiQpel2etoG0="
    }
    }
}

Creates a new creative

HTTP Request

POST /v2/companies/:companyUUID/creatives

Body Parameters

Parameter Default Data Type Description
creative_name true string Pronounceable name of the creative
advertiser_id true string The UUID of the advertiser
status true boolean The status of the creative is active or inactive. This is used to determine if the creative should be used inside a campaign, and allows the advertiser to quickly turn things on and off without updating the whole campaign.
filename true string The file name of the creative including the file extension
tags false array An array of tags to attach to the creative
start_flight_date false string The start flight date of the creative. Expecting date format Y-M-D
end_flight_date false string The end flight date of the creative. Expecting date format Y-M-D
events false array The pixel events to be attached to the creative
companion_ad false json The companion ad to be attached to the creative

Update a creative

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/creatives/9999 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
            "creative_name": "Snarkys 30 sec Christmas spot",
            "advertiser_id": "1234-abcd-qwer-xcvb",
            "status": true,
            "tags": ["30 secs", "sarcastic", "testing", "young"],
            "start_flight_date": "2022-12-01",
            "end_flight_date": "2023-01-01",
            "campaigns": [123,124,125]
            "events": [
                {
                    "Type": "Impressions",
                    "url": "https://facebook.com/pixel?campaign=1234556543321"
                }
            ],
            "companion_ad": {
                "click_through_url": "https://snarkyspizza.com/?campaign=32123456&reference=1234567654321
                "display_asset_filename": "eat-at-snarkys-christmas-spot.png"
            }
        }

    }'

Response sample

200 OK

{
    "Creative": 9999,
    "s3_displayad": {
        "url": "https://ah-advertiser-creatives.s3.amazonaws.com/",
        "fields": {
            "key": "1234-abcd-qwer-xcvb/creatives/9999/audioad.mp3",
            "AWSAccessKeyId": "ASHJDUIASHIUDASHDUIASHdi",
            "policy": "eyJleHBpcmF0aW9uIjogIjIwMjMtMDItMTNUMTk6MjE6NThaIiwgImNvbmRpdGlvbnMiOiBbeyJidWNrZXQiOiAiYWgtYWR2ZXJ0aXNlci1jcmVhdGl2ZXMifSwgeyJrZXkiOiAiZmU5NTMxMGUtNmY2Zi00YWFkLWFhZDYtYzE4YWE3ZDg0ZWM3L2NyZWF0aXZlcy80OTM4L2Rpc3BsYXlhZC5qcGcifV19",
            "signature": "vcCO8aXZNoP7X7S9wNYrl0dKUZM="
        }
    }
}

Updates a creative

HTTP Request

PATCH /v2/companies/:companyUUID/creatives/:creativeId

Body Parameters

Parameter Default Data Type Description
creative_name false string Pronounceable name of the creative
status false boolean The status of the creative is active or inactive. This is used to determine if the creative should be used inside a campaign, and allows the advertiser to quickly turn things on and off without updating the whole campaign.
start_flight_date false string The start flight date of the creative. Expecting date format Y-M-D
end_flight_date false string The end flight date of the creative. Expecting date format Y-M-D
events false array The pixel events to be attached to the creative
events_enabled false boolean TODO
tags false array An array of tags to attach to the creative
companion_ad false json The companion ad to be attached to the creative
campaigns false array An array of campaign Ids to associate the creative to
advertiser_id false string The UUID of the advertiser

Audiences

Get all audiences

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/audiences/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
  "Audiences": [
    {
      "id": "test-audience-uuid",
      "name": "Audience test first",
      "type": 1,
      "tags": [
        "tag1",
        "tag2",
        "1337",
        "tag 3"
      ],
      "creation_date": "2022-08-25 22:42:23.665578",
      "first_party": [
        {
          "type": "url",
          "value": "http://test.com"
        },
        {
          "type": "url",
          "value": "http://new.com"
        }
      ]
    },
    {
      "id": "0ce194b3-c43d-4a93-9fc9-b1b6d4007ec3",
      "name": "Audience test third",
      "type": 2,
      "tags": [
        "tag1",
        "tag23"
      ],
      "creation_date": "2022-09-01 18:06:05.319562",
      "third_party": {
        "liveramp_ids": [
          "1008188251",
          "1006711581"
        ]
      }
    },
    {
      "id": "test-audience-uuid2",
      "name": "Shrute Farms Audience One two b",
      "type": 1,
      "tags": [
        "ee",
        "local"
      ],
      "creation_date": "2022-09-09 13:39:55.879691",
      "first_party": [
        {
          "type": "event",
          "value": "purchase"
        },
        {
          "type": "url",
          "value": "t.com"
        },
        {
          "type": "url",
          "value": "e33.com"
        }
      ]
    }
  ],
  "page": "0",
  "size": "30",
  "total_records": 2
}

Returns a list of all audiences for a company.

HTTP Request

GET /v2/companies/:companyUUID/audiences

Query Parameters

Parameter Default Data Type Description
size 30 int The total number of audiences to be sent.
page 0 int The page of audiences to return.

Get a audience

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/audiences/test-audience-uuid/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
  }'

Response sample

200 OK

{
  "Audiences": {
    "id": "test-audience-uuid",
    "name": "Test audience",
    "type": 1,
    "tags": [
        "tag1",
        "tag2",
        "1337",
        "tag 3"
    ],
    "creation_date": "2022-08-25 22:42:23.665578",
    "first_party": [
      {
          "type": "url",
          "value": "http://test.com"
      },
      {
          "type": "url",
          "value": "http://new.com"
      }
    ]
  }
}

Returns a audience with the given id.

HTTP Request

GET /v2/companies/:companyUUID/audiences/:audienceUUID

Create a audience

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/audiences/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
            "advertiser_id": "1234-abcd-qwer-xcvb",
            "name": Test audience docs,
            "tags": ["test tag 1", "test tag 2"],
            "topics": ["topic 1", "topic 2"],
            "type": 3,
        }
    }'

Response sample

200 OK

{"Audience": {"uuid": "test-audience-uuid"}}

Creates a new audience

HTTP Request

POST /v2/companies/:companyUUID/audiences

Body Parameters

Parameter Default Data Type Description
name true string The name of the new audience
advertiserId true string The UUID of the advertiser
type true int The audience type to set your audience to. Audience type 1 requires key first_party. Audience type 2 requires key liveramp_ids. Audience type 3 requires key topics
first_party false array An array of first party segments to attach to the audience. If type is onboarding then value must be either crm or cdp
liveramp_ids false array An array of liveramp ids
topics false array/string An array of topics to attach to the audience. Can signify that a csv of topics is being sent by setting topics to csv
correlation_id false string An id that correlates a audience id to a csv object in S3 with crm, cdp, or topics data. Id is generated with csvbox
tags false array An array of tags to attach to the audience

Update a audience

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/audiences/test-audience-uuid/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
            "advertiser_id": "1234-abcd-qwer-xcvb",
            "name": Test audience new name,
            "topics": ["topic 3", "topic 4"],
            "type": 3,
        }
    }'

Response sample

200 OK

{"Message": "Updated audience test-audience-uuid"}

Creates a new audience

HTTP Request

PATCH /v2/companies/:companyUUID/audiences/:audienceUUID

Body Parameters

Parameter Default Data Type Description
name true string The name of the new audience
tags false array An array of tags to attach to the audience
first_party false array An array of first party segments to attach to the audience. If type is onboarding then value must be either crm or cdp
liveramp_ids false array An array of liveramp ids
topics false array/string An array of topics to attach to the audience. Can signify that a csv of topics is being sent by setting topics to csv

Playlists

Get all playlists

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists?page=0&size=10 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Playlists": [
        {
            "uuid": "9a591a63-dcfd-4ae6-9c49-119f5c5800ca",
            "name": "Inventory large test",
            "type": "podcast",
            "inventory": [
                "4b0e1d98ac2d4c35b20437e72c34369f",
                "4bb57409ed7f498da12b5ef6017bf9e3",
                "586530ab2d634694ab4a47326d4f5fc2",
            ],
            "tags": [
                "test"
            ],
            "inventory_size": 17720,
            "created_at": "2023-06-20T19:53:22.897016",
            "updated_at": "2023-06-20T21:25:46.638180"
        },
        {
            "uuid": "88f58c84-8946-4420-ae3e-c2a42d9f3c1e",
            "name": "Podcast test 1",
            "type": "podcast",
            "inventory": [
                "d7c2ca1a523a4e56aedc750027ec52f6",
                "d7c2ca1a523a4e56aedc750027ec52f6"
            ],
            "tags": [
                "test"
            ],
            "inventory_size": 3,
            "created_at": "2023-06-16T21:49:38.580150",
            "updated_at": "2023-06-20T22:34:52.063794"
        },
        {
            "uuid": "8b35df77-eba2-4ac7-a6dd-6d462333fed3",
            "name": "Radio stations",
            "type": "radio",
            "inventory": [
                "WZJM-LP"
            ],
            "searches": [],
            "tags": [],
            "inventory_size": 1,
            "created_at": "2023-06-21T02:33:27.017964",
            "updated_at": "2023-06-21T02:33:27.017964"
        },
        {
            "uuid": "301c68bb-e30e-48b6-ad85-e5d1b293a635",
            "name": "Streaming 1",
            "type": "streaming",
            "inventory": [
                "Spotify"
            ],
            "searches": [],
            "tags": [],
            "inventory_size": 1,
            "created_at": "2023-06-21T04:20:35.684578",
            "updated_at": "2023-06-21T04:20:35.684578"
        },
    ],
    "page": 0,
    "size": 10,
    "total_records": 5,
    "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy"
}

Returns a list of all playlists for a company.

HTTP Request

GET /v2/companies/:companyUUID/playlists

Query Parameters

Parameter Default Data Type Description
size 30 int The total number of playlists to be sent.
page 0 int The page of playlists to return.
type false string The playlist type to be by filtered
ids false string The playlists ids to be requested, separated by ','

Get a playlist

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists/88f58c84-8946-4420-ae3e-c2a42d9f3c1e \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
    "Message": "",
    "type": "podcast",
    "uuid": "88f58c84-8946-4420-ae3e-c2a42d9f3c1e",
    "name": "Podcast test 1",
    "inventory": [
        "d7c2ca1a523a4e56aedc750027ec52f6",
        "d7c2ca1a523a4e56aedc750027ec52f6"
    ],
    "searches": [
        {
            "count": 1,
            "query": "the smallest search result ever",
            "facets": {
                "genres": [
                    "123",
                    "122"
                ],
                "language": [
                    "English"
                ]
            }
        }
    ],
    "tags": [
        "test"
    ],
    "inventory_size": 2,
    "created_at": "2023-06-16T21:49:38.580150",
    "updated_at": "2023-06-20T22:34:52.063794",
    "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy"
}

Returns a playlist with the given id

HTTP Request

GET /v2/companies/:companyUUID/playlists/:playlistUUID

Create a playlist

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { 
        "name": "X-Request-Header", 
        "value": "Header value"
      }
        ],
        "body": {
      "name": "Example playlist",
      "advertiser_id": "fe95310e-6f6f-4aad-aad6-c18aa7d84ec7",
      "inventory_ids": ["Spotify"],
      "searches": [],
      "type": "streaming",
      "tags": ["example 1"]
    }
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Playlist": {
        "uuid": "d9fd6ac9-041c-4fca-8cb6-267f253a0136"
    },
    "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy"
}

Creates a new playlist

HTTP Request

POST /v2/companies/:companyUUID/playlists

Body Parameters

Parameter Default Data Type Description
name true string The name of the playlist
advertiser_id true string The UUID of the advertiser

Update a playlist

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists/d9fd6ac9-041c-4fca-8cb6-267f253a0136 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { 
        "name": "X-Request-Header", 
        "value": "Header value"
      }
        ],
        "body": {
      "name": "Example playlist renamed",
      "advertiser_id": "fe95310e-6f6f-4aad-aad6-c18aa7d84ec7",
      "inventory_ids": ["Spotify"],
      "searches": [],
      "type": "streaming",
      "tags": ["example 1"]
    }
  }'

Response sample

200 OK

{
    "Message": "Updated playlist d9fd6ac9-041c-4fca-8cb6-267f253a0136",
    "type": "success",
    "_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LWI2MTc4N2M4LWVmYTMtNDI3MS04NWNkLWE0ZTk0NzA3MTY3ZiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJ.BzYMMqvsvo6MswS4jLNvEBKCASpsFzaTjPTJWy"
}

Update an existing playlist

HTTP Request

PATCH /v2/companies/:companyUUID/playlists/:playlistUUID

Body Parameters

Parameter Default Data Type Description
name true string The name of the playlist
inventory_ids true array An array of inventory Id's. Defaults to an empty array
searches true array An array of disctionarios with the query detail({query: '', filters: [], count: 0}). Defaults to an empty array
type true string One of the three playlist types: podcast, radio or streaming
tags false array An array of tags to attach to the playlist

Delete multiple playlists

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
            "playlist_ids": ["test-playlist-uuid1", "test-playlist-uuid2"]
        }
    }'

Response sample

200 OK

"Updated playlist test-playlist-uuid1, test-playlist-uuid2 has been deleted"

Delete multiple playlists under a user

HTTP Request

DELETE /v2/companies/:companyUUID/playlists

Body Parameters

Parameter Default Data Type Description
playlist_ids true array An array of playlist ids owned by the current user

Delete a playlist

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/playlists/test-playlist-uuid1 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
}'

Response sample

200 OK

"Playlist test-playlist-uuid1 has been deleted"

Delete an existing playlist

HTTP Request

DELETE /v2/companies/:companyUUID/playlists/:playlistUUID

Campaigns

Get all campaigns

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/campaigns?page=0&size=1 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Campaigns": [
        {
            "id": 123,
            "name": "Campaign docs test",
            "uuid": "al92agcw",
            "advertiser_id": 878,
            "status": false,
            "draft": false,
            "campaign_type": 1,
            "budget_type": 1,
            "pacing": 3,
            "dayparting_enabled": false,
            "devices_enabled": false,
            "max_cpm": "16.0",
            "auto_optimized": false,
            "conversion_type": 1,
            "conversion_value": "11.0",
            "start_date": "2024-07-03T06:00:00",
            "end_date": "2024-07-03T23:59:59.999999",
            "budget_value": 0,
            "archived": false,
            "max_budget_enabled": false,
            "max_daily_budget": 0,
            "attribution_partners": [],
            "audiences": [
                {
                    "id": "2e1832b8-031f-4e5e-8c7d-d828cc2b86d4",
                    "condition": "AND",
                    "sort_order": 0
                }
            ],
            "brand_safety_filter": {
                "barometer": false,
                "sounder": false,
                "adult": 0,
                "arms": 0,
                "crime": 0,
                "death": 0,
                "piracy": 0,
                "hate_speech": 0,
                "profanity": 0,
                "drugs": 0,
                "spam": 0,
                "terrorism": 0,
                "social_issue": 0
            },
            "creatives": [
                {
                    "creative_id": 456,
                    "weight": 100
                }
            ],
            "dayparting": [],
            "devices": [],
            "playlists_ui": {
                "include_radio": true,
                "include_emerging": false,
                "include_podcasts": true,
                "target_all_radio": true,
                "include_streaming": true,
                "target_all_emerging": true,
                "target_all_podcasts": true,
                "target_all_streaming": true,
                "exclude_radio_playlist_ids": [],
                "include_radio_playlist_ids": [],
                "exclude_podcast_playlist_ids": [],
                "include_podcast_playlist_ids": [],
                "exclude_emerging_playlist_ids": [],
                "include_emerging_playlist_ids": [],
                "exclude_streaming_playlist_ids": [],
                "include_streaming_playlist_ids": []
            },
            "geo_ui": [],
            "goal_optimization": "no-optimizations",
            "playlists_weights": null,
            "weighted_delivery": false,
            "impressions": null,
            "spend": null,
            "duration": 0
        }
    ],
    "page": "0",
    "size": "1",
    "total_records": 112,
    "_token": "<auth-token>"
}

Returns a list of all campaigns for an advertiser.

HTTP Request

GET /v2/companies/:companyUUID/campaigns?advertiserId=<uuid>

Query Parameters

Parameter Default Data Type Description
page 0 int The page of audiences to return.
size 100 int The total number of audiences to be sent.
q None string Search by campaign name
archive false boolean A boolean to return either archived campaigns or non-archived campaigns. Defaults to False
status false boolean A boolean to return campaigns of a certain status. Acceptable values: active-running, active, inactive, all. Defaults to all
startDate -1 string The start date of receiving data. Expected date format Y-M-D. Defaults to -1 (everything)
endDate -1 string The end date of receiving data. Expected date format Y-M-D. Defaults to -1 (everything)
order_by None string Order the response based off a key. Ex: name-ORDER (Sorts response by campaign names)
data true boolean Retrieve total impresions, total spend, total conversions, and cost per conversions for each campaign.
campaign_ids_data None string A comma separated list of campaign ids to retrieve data for.

Get a campaign

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/campaigns/44444 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ]
}'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "id": 123,
    "name": "Campaign docs test",
    "uuid": "12bfoe3t",
    "advertiser_id": 456,
    "status": true,
    "draft": false,
    "campaign_type": 1,
    "budget_type": 1,
    "pacing": 5,
    "dayparting_enabled": false,
    "devices_enabled": false,
    "max_cpm": "16.0",
    "auto_optimized": false,
    "conversion_type": 1,
    "conversion_value": "16.0",
    "start_date": "2024-06-25T06:00:00",
    "end_date": "2024-06-25T23:59:59.999999",
    "budget_value": 0,
    "archived": false,
    "active_running": false,
    "max_budget_enabled": false,
    "max_daily_budget": 0,
    "attribution_partners": [],
    "audiences": [],
    "brand_safety_filter": {
        "barometer": false,
        "sounder": false,
        "adult": 0,
        "arms": 0,
        "crime": 0,
        "death": 0,
        "piracy": 0,
        "hate_speech": 0,
        "profanity": 0,
        "drugs": 0,
        "spam": 0,
        "terrorism": 0,
        "social_issue": 0
    },
    "creatives": [],
    "dayparting": [],
    "devices": [],
    "playlists_ui": {
        "include_radio": true,
        "include_emerging": false,
        "include_podcasts": true,
        "target_all_radio": true,
        "include_streaming": true,
        "target_all_emerging": true,
        "target_all_podcasts": true,
        "target_all_streaming": true,
        "exclude_radio_playlist_ids": [],
        "include_radio_playlist_ids": [],
        "exclude_podcast_playlist_ids": [],
        "include_podcast_playlist_ids": [],
        "exclude_emerging_playlist_ids": [],
        "include_emerging_playlist_ids": [],
        "exclude_streaming_playlist_ids": [],
        "include_streaming_playlist_ids": []
    },
    "geo_ui": [],
    "goal_optimization": "no-optimizations",
    "playlists_weights": {
        "radio": {
            "weight": 10,
            "playlists": []
        },
        "emerging": {
            "weight": 10,
            "playlists": []
        },
        "podcasts": {
            "weight": 10,
            "playlists": []
        },
        "streaming": {
            "weight": 10,
            "playlists": []
        }
    },
    "weighted_delivery": false,
    "_token": "<auth-token>"
}

Returns a campaign with the given id

HTTP Request

GET /v2/companies/:companyUUID/campaigns/:campaignID

Create a new campaign

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/campaigns \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
  "draft": false,
  "campaign_type": 1,
  "name": "Test campaign Docs",
  "pacing": "5",
  "status": false,
  "budget_type": 1,
  "budget_value": 1,
  "start_date": "2023-02-15",
  "end_date": "2023-02-16",
  "audiences": [
    {
      "id": "110d1c94-5b25-47c9-8fb9-1c51a42cbb16",
      "condition": "AND",
      "sort_order": 0
    }
  ],
  "dayparting_enabled": false,
  "dayparting": [],
  "geo_ui": [
    {
      "placeId": "ChIJrxNRX7IFzkwRCR5iKVZC-HA",
      "name": "Ontario, Canada",
      "type": "include"
    }
  ],
  "google_places": [
    {
      "address_components": [
        {
          "long_name": "Ontario",
          "short_name": "ON",
          "types": [
            "administrative_area_level_1",
            "political"
          ]
        },
        {
          "long_name": "Canada",
          "short_name": "CA",
          "types": [
            "country",
            "political"
          ]
        }
      ],
      "adr_address": "<span class=\"region\">Ontario</span>, <span class=\"country-name\">Canada</span>",
      "formatted_address": "Ontario, Canada",
      "geometry": {
        "location": {
          "lat": 51.253775,
          "lng": -85.3232139
        },
        "viewport": {
          "south": 41.67655592548799,
          "west": -95.15622705030871,
          "north": 56.93139296124655,
          "east": -74.32064792950113
        }
      },
      "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png",
      "icon_background_color": "#7B9EB0",
      "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/companies/:companyUUID/generic_pinlet",
      "name": "Ontario",
      "photos": [
        {
          "height": 360,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/111007979254365808386\">reza karami</a>"
          ],
          "width": 596
        },
        {
          "height": 360,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/111007979254365808386\">reza karami</a>"
          ],
          "width": 542
        },
        {
          "height": 357,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/108933587345666100977\">Jassim Anwar</a>"
          ],
          "width": 612
        },
        {
          "height": 1800,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/103108653966718782017\">Rami Choullami</a>"
          ],
          "width": 4000
        },
        {
          "height": 2097,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/114569031420435595834\">B S</a>"
          ],
          "width": 1896
        },
        {
          "height": 386,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/106831841410328247524\">Puppy Chonkers</a>"
          ],
          "width": 686
        },
        {
          "height": 1800,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/103108653966718782017\">Rami Choullami</a>"
          ],
          "width": 4000
        },
        {
          "height": 3024,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/108474065684880135906\">abdelmajid ouazine</a>"
          ],
          "width": 4032
        },
        {
          "height": 3456,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/104210009813670010562\">F Williams</a>"
          ],
          "width": 3456
        },
        {
          "height": 1871,
          "html_attributions": [
            "<a href=\"https://maps.google.com/maps/contrib/116789881332166351131\">Mikaël Gravé</a>"
          ],
          "width": 9785
        }
      ],
      "place_id": "ChIJrxNRX7IFzkwRCR5iKVZC-HA",
      "reference": "ChIJrxNRX7IFzkwRCR5iKVZC-HA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "url": "https://maps.google.com/?q=Ontario,+Canada&ftid=0x4cce05b25f5113af:0x70f8425629621e09",
      "utc_offset": -300,
      "website": "http://www.ontario.ca/",
      "html_attributions": [],
      "utc_offset_minutes": -300
    }
  ],
  "devices_enabled": false,
  "playlists": [
    "test-playlist-uuid"
  ],
  "brand_safety_filter": {
    "barometer": true,
    "sounder": false,
    "adult": 2,
    "arms": 0,
    "crime": 0,
    "death": 0,
    "piracy": 0,
    "hateSpeech": 0,
    "profanity": 0,
    "drugs": 0,
    "spam": 0,
    "terrorism": 0,
    "socialIssue": 0
  },
  "creatives": [
    {
      "creative_id": 4957,
      "weight": "100"
    }
  ],
  "auto_optimized": true,
  "conversion_type": 1,
  "conversion_value": "1",
  "goal_optimization": "no-optimizations",
  "advertiser_id": "test-advertiser-uuid"
}
    }'

Response sample

200 OK

{
  "Message": "Campaign 823479 has been updated successfully",
  "Campaign_id": 823479
}

Creates a new campaign

HTTP Request

POST /v2/companies/:companyUUID/campaigns

Body Parameters

Parameter Default Data Type Description
draft true boolean The draft state of the campaign
campaign_type true int The type of campaign. 1 - Pay for impression, 2 - CPA
name true string The name of the new campaign
pacing true int The pacing selected for the campaign. 1 - As fast as possible, 2 - Fixed daily, 3 - Front loaded, 4 - Back loaded, 5 - Event - Adaptive Daily Pacing, 6 - Even - Adaptive Lifetime pacing
status true boolean If the campaign is active or not
budget_type true int The budget type of the campaign. 1 - Dollars, 2 - Impressions
budget_value true int The budget of the campaign
start_date true string The start date of the campaign. Expecting date format Y-M-D
end_date true string The end date of the campaign. Expecting date format Y-M-D
audiences false array An array of json objects containing information about the selected audiences
dayparting_enabled true boolean If dayparting is enabled for the campaign
dayparting false array An array of json objects containing information about each day
geo_ui false array An array of json objects containing information about the geography selected for the campaign
google_places false array An array of raw json objects from the google places api containing all information about each place selected
devices_enabled true boolean If devices is enabled for the campaign
brand_safety_filter true json A json containing the information about the selected brand safety filter settings
creatives false array An array of json containing information about each creative selected. If priority is selected, the value must not exceeed the total amount of creatives. If weight is selected, the total amount of weights must not exceed 100. Mixing priority and weight would result in an error
auto_optimized true boolean If the campaign is going to be auto optimized or not
conversion_type true int The conversion type selected for the campaign. 1 - Website Visits, 2 - Leads, 3 - Purchases, 4 - In Store Visits, 5 - App downloads, 6 - Custom Conversion, 7 - Reach, 8 - Form Completion
conversion_value true float The conversion value selected for the conversion type
goal_optimization true string The goal optimization selected for the campaign. Must be no optimizations, partial-optimizations, or full-optimizations
advertiser_id true string The advertiser UUID to create the campaign under

Update a campaign

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/campaigns \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
        ],
        "body": {
  "name": "Test campaign Docs",
  "advertiser_id": "test-advertiser-uuid"
}
    }'

Response sample

200 OK

{
  "Message": "Campaign 823479 has been updated successfully",
  "Campaign_id": 823479
}

Update an existing campaign

HTTP Request

PATCH /v2/companies/:companyUUID/campaigns

Body Parameters

Parameter Default Data Type Description
draft false boolean The draft state of the campaign
campaign_type false int The type of campaign. 1 - Pay for impression, 2 - CPA
name false string The name of the new campaign
pacing false int The pacing selected for the campaign. 1 - As fast as possible, 2 - Fixed daily, 3 - Front loaded, 4 - Back loaded, 5 - Event - Adaptive Daily Pacing, 6 - Even - Adaptive Lifetime pacing
status false boolean If the campaign is active or not
budget_type false int The budget type of the campaign. 1 - Dollars, 2 - Impressions
budget_value false int The budget of the campaign
start_date false string The start date of the campaign. Expecting date format Y-M-D
end_date false string The end date of the campaign. Expecting date format Y-M-D
audiences false array An array of json objects containing information about the selected audiences
dayparting_enabled false boolean If dayparting is enabled for the campaign
dayparting false array An array of json objects containing information about each day
geo_ui false array An array of json objects containing information about the geography selected for the campaign
google_places false array An array of raw json objects from the google places api containing all information about each place selected
devices_enabled false boolean If devices is enabled for the campaign
brand_safety_filter false json A json containing the information about the selected brand safety filter settings
creatives false array An array of json containing information about each creative selected. If priority is selected, the value must not exceeed the total amount of creatives. If weight is selected, the total amount of weights must not exceed 100. Mixing priority and weight would result in an error
auto_optimized false boolean If the campaign is going to be auto optimized or not
conversion_type false int The conversion type selected for the campaign. 1 - Website Visits, 2 - Leads, 3 - Purchases, 4 - In Store Visits, 5 - App downloads, 6 - Custom Conversion, 7 - Reach, 8 - Form Completion
conversion_value false float The conversion value selected for the conversion type
goal_optimization false string The goal optimization selected for the campaign. Must be no optimizations, partial-optimizations, or full-optimizations
advertiser_id true string The advertiser UUID to create the campaign under

Delete a campaign

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/campaigns/837429 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
    }'

Response sample

200 OK

{"Message": "Campaign has been deleted!", "Campaign_id": 837429}

Delete an existing campaign that the user owns

HTTP Request

DELETE /v2/companies/:companyUUID/campaigns/:campaignID

Companies

Get all companies

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
    }'

Response sample

200 OK

{
  "Advertisers": [
    {
      "uuid": "test-advertiser-uuid",
      "name": "Test advertiser name",
      "logo_url": "https://audiohook-assets.s3.us-east-1.amazonaws.com/test-advertiser-uuid/logo.jpeg",
      "url": "https://testwebsite.com",
      "status": true,
      "reporting_requested": false,
      "glean_url": null,
      "onboarded": true
    },
    {
      "uuid": "test-advertiser-uuid2",
      "name": "Test advertiser name 2",
      "logo_url": "https://audiohook-assets.s3.us-east-1.amazonaws.com/test-advertiser-uuid2/logo.jpeg",
      "url": "https://www.testwebsite2.com/",
      "status": true,
      "reporting_requested": false,
      "glean_url": null,
      "onboarded": true
    }
  ]
}

Get all companies under the current user/agency

HTTP Request

GET /v2/companies

Get a company

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Advertiser": {
        "uuid": "0408c71a-1977-4a03-9697-36b7f4d85e1f",
        "name": "Test advertiser",
        "category": "IAB1-3",
        "logo_url": "https://media2.audiohook.com/some-uuid/logo.jpeg",
        "url": "https://afakeurl.com",
        "status": true,
        "approved": false,
        "dashboard": 3,
        "onboarded": true,
        "user_role": 1,
        "associated_agency_uuid": null,
        "associated_agency_name": null,
        "deals": [
            "pmp-id"
        ]
    },
    "_token": "<auth-token>"
}

Get a company using the company uuid

HTTP Request

GET /v2/companies/:companyUUID

Search for companies

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/search/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Advertisers": [
        {
            "uuid": "be95d3f6-e875-4284-84be-413ffb0d83f1",
            "name": "Advertiser A"
        },
        {
            "uuid": "a8e89eca-d505-4bb9-975e-73dbec0df63a",
            "name": "Advertiser B"
        },
        {
            "uuid": "df7d86bc-277d-4982-a4c9-6727aab21eaf",
            "name": "Advertiser C"
        }
        ],
    "_token": "<auth-token>"
}

Get all companies uuid's and names under the user

HTTP Request

GET /v2/companies/search

Create a company

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "body": {
            "name": "test-advertiser",
      "url": "https://www.testadvertisersite.com,
      "category": "IAB3-1",
      "filename": "mylogo.png"
        }
    }'

Response sample

200 OK

{
  "Advertiser": {
    "Advertiser": {
      "id": 999999,
      "uuid": "test-advertiser-uuid"
    }
  },
  "s3_data": {
    "url": "https://ah-advertiser-creatives-input.s3.amazonaws.com/",
    "fields": {
      "key": "test-advertiser-uuid/logo_mylogo.png",
      "AWSAccessKeyId": "ASHJDUIASHIUDASHDUIASHdi",
      "policy": "eyJleHBpcmF0aW9uIjogIjIwMjMtMDItMTBUMDA6NDI6MDJaIiwgImNvbmRpdGlvbnMiOiBbeyJidWNrZXQiOiAiYWgtYWR2ZXJ0aXNlci1jcmVhdGl2ZXMtaW5wdXQifSwgeyJrZXkiOiAiZmU5NTMxMGUtNmY2Zi00YWFkLWFhZDYtYzE4YWE3ZDg0ZWM3L2NyZWF0aXZlcy80OTQxL2F1ZGlvYWQubXAzIn1dfQ==",
      "signature": "ejEoRYAWr7iRJKPaugKgsQul5UY="
    }
  }
}

Create a new company

HTTP Request

POST /v2/companies

Body Parameters

Parameter Default Data Type Description
name true string The name of the advertiser
url true string The url that is associated with the advertiser
category true string The IAB category associated with the advertiser
filename false string The file name of the advertiser's logo including the file extension
status false boolean The status of the advertiser. Defaults to true
account_type false string The account type of the advertiser. Defaults to audiohook
trial false boolean If the advertiser is in a trial or not (?). Defaults to true
owner_id false int The user id to put the advertiser under. Defaults to the current user's id

Update a company

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "body": {
            "name": "test-advertiser"
        }
    }'

Response sample

200 OK

{ "Message": "Advertiser 999999 has been updated", "Advertiser": {"id": 999999, "uuid": "test-advertiser-uuid"}}

Updates an existing company

HTTP Request

PATCH /v2/companies/:companyUUID

Body Parameters

Parameter Default Data Type Description
name false string The name of the advertiser
url false string The url that is associated with the advertiser
status false boolean The status of the advertiser. Defaults to true
owner_id false int The user id to put the advertiser under. Defaults to the current user's id
reporting_requested false boolean Whether or not the advertiser requested Glean reporting
onboarded false boolean Whether the advertiser has finished onboarding

Delete a company

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{ "Message": "Advertiser 999999 has been deleted", "Advertiser": {"uuid": "test-advertiser-uuid"} }

Delete an existing company

HTTP Request

DELETE /v2/companies/:companyUUID

Payment methods

Get companies payment methods

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/payment-methods \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "PaymentMethods": {
        "id": 123,
        "buyer_id": "byr_id",
        "payment_id": "pm_id",
        "terms": "month",
        "calendar": "traditional",
        "type": "creditCard",
        "advertiser_id": 456
    },
    "BalanceBuyer": {
        "statusCode": 403,
        "message": "Forbidden"
    },
    "_token": "<auth-token>"
}

Gets a list of payment methods for a buyer. Also returns the Balance buyer response.

HTTP Request

GET /v2/companies/:companyUUID/payment-methods

Create companies payment method

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/payment-methods \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "body": {
            "buyer_id": "test-byr_sofkpsdkf89345sdfjgoisdfj",
      "payment_id": "pm_j49302AIOSDFfiosdf390",
      "terms": "month",
      "calendar": "traditional",
      "type": creditCard
        }
    }'

Response sample

200 OK

{"Message": "Payment method saved.", "PaymentMethod": {"id": -1, "buyer_id": "byr_sofkpsdkf89345sdfjgoisdfj", "payment_id": "pm_j49302AIOSDFfiosdf390", "terms": "month", "calendar": "traditional", "type": "creditCard", "advertiser_id": 999999}}

Creates a payment method for a company

HTTP Request

POST /v2/companies/:companyUUID/payment-methods

Body Parameters

Parameter Default Data Type Description
buyer_id true string The id of the buyer
payment_id true string The id of the payment
terms true string Ther term of the payment method
calendar true string The calendar of the payment method. Valid values: traditional, broadcast
type true string The type of the payment. Valid values: card, bank

Update advertiser payment method

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/payment-methods/pm_id \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
      "body": {
            "type": "bank"
        }
    }'

Response sample

200 OK

{"Message": "Payment method saved.", "PaymentMethod": {"id": -1, "buyer_id": "byr_sofkpsdkf89345sdfjgoisdfj", "payment_id": "pm_j49302AIOSDFfiosdf390", "terms": "month", "calendar": "traditional", "type": "bank", "advertiser_id": 999999}}

update a payment method for a company

HTTP Request

PATCH /v2/companies/:companyUUID/payment-methods/:payment-method-id

Body Parameters

Parameter Default Data Type Description
terms false string The term of the payment method
calendar false string The calendar of the payment method. Valid values: traditional, broadcast
type false string The type of the payment. Valid values: creditCard, bank

Delete payment method

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/payment-methods/pm_id \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
    "Message": "Payment method deleted.",
    "paymentMethod": "pm_id",
    "_token": "<auth-token>"
}

Delete a payment method for a company

HTTP Request

DELETE /v2/companies/:companyUUID/payment-methods/:payment-method-id

Payment token

Create companies payment token

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/payment_token \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
      "body": {
            "buyer_id": "byr_sofkpsdkf89345sdfjgoisdfj"
        }
    }'

Response sample

200 OK

{"PaymentToken": {}}

Create a payment token for a company

HTTP Request

POST /v2/companies/:companyUUID/payment_token

Body Parameters

Parameter Default Data Type Description
buyer_id true string The id of the buyer
test false string To test the buyers api. Defaults to false

Billing info

Get companies billing info

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/billing-info \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
  "Message": "",
  "type": "success",
  "BillingInfo": {
    "id": 111,
    "advertiser_id": "test-advertiser-id",
    "buyer_id": "byr_hhj45k35h4j3j5k34",
    "company_name": "Test company",
    "address_1": "123 Fake Street",
    "address_2": "",
    "city": "Layton",
    "state": "UT",
    "country_code": "US",
    "zip": "84040",
    "phone": "1234567890",
    "email": "testemail@example.com",
    "has_payment_method": true,
    "credit_limit": "0",
    "tax_id": "12-3456789",
    "terms": "delivery",
    "calendar": "traditional",
    "balance": "0",
    "created_at": "2023-03-06T16:53:35.799667",
    "updated_at": "2023-03-06T16:53:35.799667",
    "is_child": false
  },
  "_token": "<auth-token>"
}

Get companies billing info

HTTP Request

GET /v2/companies/:companyUUID/billing-info

Create companies billing info

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/billing-info \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "body": {
      "company_name": "Audiohook Sub"
      "address_1": "123 Fake Street",
      "address_2": "",
      "city": "Layton",
      "state": "UT",
      "zip": "84040"
      "country_code": "US",
      "phone": "1234567890",
      "email": "testemail@example.com"
      "tax_id": "12-3456789"
    }
    }'

Response sample

200 OK

{ 
  "Message": "Billing info saved.", 
  "BillingInfo": {
    "id": 111,
    "advertiser_id": "test-advertiser-id",
    "buyer_id": "byr_hhj45k35h4j3j5k34",
    "company_name": "Test company",
    "address_1": "123 Fake Street",
    "address_2": "",
    "city": "Layton",
    "state": "UT",
    "country_code": "US",
    "zip": "84040",
    "phone": "1234567890",
    "email": "testemail@example.com",
    "has_payment_method": true,
    "credit_limit": "0",
    "tax_id": "12-3456789",
    "terms": "delivery",
    "calendar": "traditional",
    "balance": "0",
    "created_at": "2023-03-06T16:53:35.799667",
      "updated_at": "2023-03-06T16:53:35.799667",
      "is_child": false
  }, 
  "CreditStatus": "" ,
  "_token": "<auth-token>"
}

Create billing info for a company

HTTP Request

POST /v2/companies/:companyUUID/billing-info

Body Parameters

Parameter Default Data Type Description
company_name true string The business name to associate the billing information with
addressLine1 true string The address to associate the billing information with
city true string The city to associate the billing information with
zipCode true string The zip code to associate the billing information with
state true string The state to associate the billing information with
zip true string The address zip code to associate the billing information with
countryCode true string The country code to associate the billing information with
phone true string The phone number to associate the billing information with
email true string The email to associate the billing information with
tax_id true string The tax id to associate the billing information with

Update companies billing info

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/billing-info \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "body": {
      "company_name": "Audiohook Sub"
      "address_1": "123 Fake Street",
      "address_2": "",
      "city": "Layton",
      "state": "UT",
      "zip": "84040"
      "country_code": "US",
      "phone": "1234567890",
      "email": "testemail@example.com"
      "tax_id": "12-3456789"
    }
    }'

Response sample

200 OK

{ 
  "Message": "Billing info saved.", 
  "BillingInfo": {
    "id": 111,
    "advertiser_id": "test-advertiser-id",
    "buyer_id": "byr_hhj45k35h4j3j5k34",
    "company_name": "Test company",
    "address_1": "123 Fake Street",
    "address_2": "",
    "city": "Layton",
    "state": "UT",
    "country_code": "US",
    "zip": "84040",
    "phone": "1234567890",
    "email": "testemail@example.com",
    "has_payment_method": true,
    "credit_limit": "0",
    "tax_id": "12-3456789",
    "terms": "delivery",
    "calendar": "traditional",
    "balance": "0",
    "created_at": "2023-03-06T16:53:35.799667",
      "updated_at": "2023-03-06T16:53:35.799667",
      "is_child": false
  }, 
  "CreditStatus": "" ,
  "_token": "<auth-token>"
}

Update billing info for a company

HTTP Request

PATCH /v2/companies/:companyUUID/billing-info

Body Parameters

Parameter Default Data Type Description
company_name true string The business name to associate the billing information with
addressLine1 true string The address to associate the billing information with
city true string The city to associate the billing information with
zipCode true string The zip code to associate the billing information with
state true string The state to associate the billing information with
zip true string The address zip code to associate the billing information with
countryCode true string The country code to associate the billing information with
phone true string The phone number to associate the billing information with
email true string The email to associate the billing information with
tax_id true string The tax id to associate the billing information with

Clients

Get clients

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/clients/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: AGENCY" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Clients": [
        {
            "uuid": "53201645-5afd-4702-91e9-9ca427f6ca72",
            "name": "Advertiser A",
            "logo_url": "https://media2.audiohook.com/dev/53201645-5afd-4702-91e9-9ca427f6ca72/logo.png",
            "active_campaigns": 28,
            "total_campaigns": 190
        },
        {
            "uuid": "665bb8e4-6e4c-41b8-8f4f-337cf931216a",
            "name": "Advertsier B",
            "logo_url": "https://media2.audiohook.com/665bb8e4-6e4c-41b8-8f4f-337cf931216a/logo.jpeg",
            "active_campaigns": 13,
            "total_campaigns": 88
        }
    ],
    "page": 0,
    "size": 30,
    "total_records": 2,
    "_token": "<auth-token>"
}

Get all clients/companies under an agency

HTTP Request

GET /v2/companies/:companyUUID/clients

Query Parameters

Parameter Default Data Type Description
page 0 string The page of team members to start at.
size 30 string The amount of members to return in a page.
q None string Search by client name

Teams

Get team members

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/teams/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
  "Members": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "JohnDoe@example.com",
      "role_id": 2,
      "user_id": -1,
      "advertiser_id": 99999,
      "total_records": 1
    }
  ],
  "total_records": 1,
  "page": 1,
  "size": 1
}

List all team members for an advertiser

HTTP Request

GET /v2/companies/:companyUUID/teams

Query Parameters

Parameter Default Data Type Description
page false string The page of team members to start at. Defaults to 1
size false string The amount of members to return in a page. Defaults to 10

Create team members

Request example

curl -X POST https://betaapi.audiohook.com/v2/companies/:companyUUID/teams/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "Body": {
      "email": "johndoe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "role": "3"
    }
    }'

Response sample

200 OK

{"success": true, "users": [-1]}

Add a team member to a team

HTTP Request

POST /v2/companies/:companyUUID/teams

Body Parameters

Parameter Default Data Type Description
email false string The email of the team member
first_name false string The first name of the team member
last_name false string The first name of the team member
role false string The role of the team member
role_id false string The role id that is associated with the given role

Update a team member

Request example

curl -X PATCH https://betaapi.audiohook.com/v2/companies/:companyUUID/teams/-1 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }],
    "Body": {
      "role_id": "1"
    }
    }'

Response sample

200 OK

{"role_id": 1}

Update a team members role

HTTP Request

PATCH /v2/companies/:companyUUID/teams/:userId

Body Parameters

Parameter Default Data Type Description
role_id false string The role id that is associated with the given role

Delete a team member

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/teams/-1 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{"success": true}

Delete a team member from the team

HTTP Request

DELETE /v2/companies/:companyUUID/teams/:userId

Users

Get a user

Request example

curl -X GET https://betaapi.audiohook.com/v2/users/me \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: ADVERTISER" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

  {
  "first_name": "John",
  "last_name": "Doe",
  "email": "johndoe@example.ocm",
  "userId": "asidojfoidsfjios",
}

Return information about the current user

HTTP Request

GET /v2/users/me

Delete a user

Request example

curl -X DELETE https://betaapi.audiohook.com/v2/companies/:companyUUID/users/-5 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

-2

Disassociate a user from all it's advertisers

HTTP Request

DELETE /v2/companies/:companyUUID/users/:userId

Integrations

Get all integrations

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/integrations/ \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: AGENCY" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Integrations": [
        {
            "id": "barometer",
            "name": "Barometer",
            "section": "Brand Suitability",
            "description": "Barometer is an AI-powered brand suitability and contextual targeting solution. Use our filters to align with the perfect content for your campaign while staying true to your brand values.",
            "available": false,
            "uuid": null,
            "type": null,
            "location": null,
            "credentials": null,
            "status": false
        },
        {
            "id": "sounder",
            "name": "Sounder",
            "section": "Brand Suitability",
            "description": "Sounder. AI provides the best available targeting and brand suitability solutions for podcast advertising. We are trusted by the largest audio companies in the world to maximize audio advertising potential.",
            "available": false,
            "uuid": null,
            "type": null,
            "location": null,
            "credentials": null,
            "status": false
        },
        {
            "id": "export",
            "name": "Data Export Tool",
            "section": "Data Export",
            "description": "Seamlessly store and access your data with our integrated AWS S3 app, providing reliable and scalable cloud storage solutions.",
            "available": true,
            "uuid": null,
            "type": null,
            "location": null,
            "credentials": null,
            "status": false
        },
        {
            "id": "snowflake",
            "name": "Snowflake",
            "section": "Data Warehouse",
            "description": "Snowflake is a cloud data warehousing platform that offers a highly scalable and flexible data storage and analytics solution, designed to help organizations efficiently manage and analyze vast amounts of data in a cloud-native environment. It stands out for its separation of storage and compute, enabling users to scale resources independently and perform data analytics at scale with ease.",
            "available": false,
            "uuid": null,
            "type": null,
            "location": null,
            "credentials": null,
            "status": false
        }
    ],
    "total_records": 4,
    "page": 0,
    "size": 30,
    "_token": "<auth-token>"
}

Get all integrations under a company

HTTP Request

GET /v2/companies/:companyUUID/integrations

Query Parameters

Parameter Default Data Type Description
page 0 integer The page of integrations to return.
size 30 integer The total number of integrations to be sent.
order_by section asc string Order the response based off a key

Get a integration

Request example

curl -X GET https://betaapi.audiohook.com/v2/companies/:companyUUID/integrations/some-integration-uuid \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "ui-referer: AGENCY" \
  -d '{
        "request_headers": [
            { "name": "X-Request-Header", "value": "Header value" }]
    }'

Response sample

200 OK

{
    "Message": "",
    "type": "success",
    "Integration": {
        "id": "export",
        "name": "Data Export Tool",
        "section": "Data Export",
        "description": "Seamlessly store and access your data with our integrated AWS S3 app, providing reliable and scalable cloud storage solutions.",
        "available": true,
        "uuid": "a4a2c58e-c8fb-4669-b9c1-b3a7c7af872c",
        "type": "s3",
        "location": "some-bucket/some-prefix",
        "credentials": {
            "s3": {
                "access": "aws-access-key",
                "secret": "aws-secret-key"
            }
        },
        "status": true,
        "full_count": 1
    },
    "_token": "<auth-token>"
}

Get a integration under a agency

HTTP Request

GET /v2/companies/:companyUUID/integrations/:integrationUUID

shell