API documentation  /leads-blacklist/phone-numbers

These are the API docs of the demo platform. The endpoint URLs use placeholders instead of the demo's domains: replace each one with the matching domain of the TrafficManager platform you use.
  • {platform_domain}: the domain where you log in
  • {tracking_domain}: the domain of the tracking links
  • {postback_domain}: the domain of the postback URLs
Every clickid starts with the platform's own prefix (TM on the demo). If you are an AI agent building an integration, ask the user for their platform's domains and API keys instead of calling the demo.

List, add or check the phone numbers of the leads blacklist. A lead whose phone number is blacklisted is treated as trash as soon as it arrives, with the note "BLACKLISTED - phone number is blacklisted".

GET https://{platform_domain}/api/v1/leads-blacklist/phone-numbers
POST https://{platform_domain}/api/v1/leads-blacklist/phone-numbers
POST https://{platform_domain}/api/v1/leads-blacklist/phone-numbers/check

The endpoints are available only for admin and advertiser accounts. Each account works on the list it sees on the Leads → Blacklist page: admins on the list that applies to all the leads of the platform, advertisers on their own list, which applies to the leads they receive.

Authentication:

The request must be authenticated with the following HTTP headers:
  • x-api-key: Your API key, found on the Security page
  • x-user-id: Your User ID, found on the Security page
If the HTTP headers are not passed, but you are logged in to the TrafficManager panel, the current user is used instead (so you can easily preview or download the data using your browser)

Phone numbers

The tel parameter accepts a number with or without its international prefix: for Italy, +39 335 123 4567, 0039 335 123 4567 and 335 123 4567 are the same number. Spaces, dashes, dots and brackets are ignored.

A number without the international prefix is read as a number of the country parameter, a two-letter ISO 3166-1 code such as IT. Without it, the default region selected on the Leads → Blacklist page is used (Italy, unless it was changed). A number starting with + is read the same way whatever the country, while 00 works only where it is the prefix for calling abroad, as in Italy: prefer the + form. When sent, country must be a valid code, even for a + number.

Only valid phone numbers are accepted: anything else is answered with a 400 error, so an invalid number is never added, nor reported as not blacklisted. The responses contain the number as it is stored, in the international E.164 format, for example +393351234567.

GET: list the blacklisted numbers

Returns all the phone numbers in the list, in the same order as on the Leads → Blacklist page. Numbers added on the Leads → Blacklist page that could not be validated are listed as they were entered, keeping only the digits and the + sign.

curl --location 'https://{platform_domain}/api/v1/leads-blacklist/phone-numbers' \
--header 'x-user-id: 04120c02-b144-439f-9f0a-85824e66fc00' \
--header 'x-api-key: TM04dca746122da971e02d55d496ebc457f20a8300'
{
    "status": 200,
    "phoneNumbers": [
        "+393351234567",
        "+393479876543"
    ]
}

POST: add a number

Parameters, sent as form data or as JSON:

  • tel: the phone number (required)
  • country: the country of a number without its international prefix (optional, see above)

The number is added to the list and to the text of the Leads → Blacklist page, where it can be removed. A number that is already in the list is not added again, and the response says "added": false.

curl --location --request POST 'https://{platform_domain}/api/v1/leads-blacklist/phone-numbers' \
--header 'x-user-id: 04120c02-b144-439f-9f0a-85824e66fc00' \
--header 'x-api-key: TM04dca746122da971e02d55d496ebc457f20a8300' \
--form 'tel=335 123 4567' \
--form 'country=IT'
{
    "status": 200,
    "phoneNumber": "+393351234567",
    "added": true
}

POST: check a number

Same parameters as above. Answers whether the number is in the list, without changing anything.

curl --location --request POST 'https://{platform_domain}/api/v1/leads-blacklist/phone-numbers/check' \
--header 'x-user-id: 04120c02-b144-439f-9f0a-85824e66fc00' \
--header 'x-api-key: TM04dca746122da971e02d55d496ebc457f20a8300' \
--header 'Content-Type: application/json' \
--data '{"tel": "+39 335 123 4567"}'
The number is blacklisted:
{
    "status": 200,
    "phoneNumber": "+393351234567",
    "blacklisted": true
}
The number is valid, but not blacklisted:
{
    "status": 200,
    "phoneNumber": "+393351234568",
    "blacklisted": false
}
The number is not valid, for example {"tel": "335 123"}:
{
    "status": 400,
    "message": "Invalid phone number"
}

Response codes:

  • 200: The request has been processed.
  • 400: Invalid request: the tel parameter is missing or is not a valid phone number, the country parameter is not a valid code, or the authentication headers are missing.
  • 403: Authentication failed, or the account is neither an admin nor an advertiser.
  • 503: The same list is being updated by another request. Please retry.

Errors repeat the response code in status, with a message explaining the reason:

{
    "status": [error code],
    "message": [error message]
}