Skip to content
outboundIQ

Assignment API

Authentication

Section titled “Authentication”

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

If the key is missing, invalid, or of the wrong type, the server will return a 401 Unauthorized or 403 Forbidden response.

Base URL

Section titled “Base URL”
https://api.outboundiq.cloud

Endpoints

Section titled “Endpoints”

Get Next ANI

Section titled “Get Next ANI”

Requests the next outbound caller ID (ANI) to use when dialing a prospect. The selector geo-matches the prospect against your inventory and returns the best available number.

  • Method: POST
  • URL: /assignment
  • Headers:
    • Authorization: Bearer YOUR_API_KEY_HERE
    • Content-Type: application/json

Body Schema:

type Payload = {
  // The prospect / customer phone number you are about to dial. 10-20
  // characters, so formatting and a calling code are fine — both are stripped
  // before matching.
  prospect_phone: string;


  // Optional US zip code for the prospect — improves geo-matching
  prospect_zip?: string;


  // The campaign identifier from your dialer platform (as saved in outboundIQ).
  // Optional if a default campaign is configured on your API key.
  dialer_campaign?: string;


  // Set to true for real-time / interactive assignment flows
  real_time?: boolean;


  // Set to true to return the assigned ANI in E.164 format. The calling code
  // is taken from the ANI's own area code, so the prefix is always correct for
  // the number returned. Defaults to false.
  e164?: boolean;


  // Country to run the selection in — 1 (US/Canada) or 44 (UK). Accepted as a
  // number or a string ("44", "+44"). Picks the geo-matching rules and limits
  // the result to that country's numbers. Omit it to leave the choice to your
  // dialer type.
  country_code?: 1 | 44;


  // Set to true to also receive a `fields` array on success — the assigned
  // ANI, the assignment timestamp, and the ANI again, each keyed by your
  // dialer's contact-record field id, in the same layout as the legacy
  // single-lead endpoint. Defaults to false.
  with_fields?: boolean;
};

Body Example:

{
  "prospect_phone": "5559876543",
  "prospect_zip": "90210",
  "dialer_campaign": "9001",
  "real_time": false,
  "e164": false
}

UK example:

Request:

{
  "prospect_phone": "7700900123",
  "dialer_campaign": "9001",
  "country_code": 44,
  "e164": true
}

Response:

{
  "success": true,
  "ani": "+447700900456",
  "message": "ANI assigned successfully"
}

Success Response:

{
  "success": true,
  "ani": "2345678901",
  "message": "ANI assigned successfully"
}

With "e164": true, the ani is returned with its calling code prefixed — "+12345678901" for a US/Canada number, "+447700900456" for a UK number.

Success Response with "with_fields": true:

{
  "success": true,
  "ani": "2345678901",
  "message": "ANI assigned successfully",
  "fields": [
    { "phone": "5559876543" },
    { "e6e7dfdb-5792-467c-a8c8-66ff55b80457": "2345678901" },
    { "34fdf497-6d71-4c78-9797-3a364bcb7372": "2026-09-11 14:05:22" },
    { "36eb0de0-b0d2-43fa-aaaf-43fbba0b11c1": "2345678901" }
  ]
}

fields is an ordered array of single-key objects: the phone you posted, then the assigned ANI, the assignment timestamp (YYYY-MM-DD HH:MM:SS, UTC), and the ANI again, each keyed by the contact-record field id configured for your dialer. Only configured fields are included, so the array may be shorter than four entries. fields is omitted on failure.

Failure Response:

{
  "success": false,
  "message": "No available ANI found"
}

Example

Section titled “Example”
Terminal window
curl -X POST \
  https://api.outboundiq.cloud/assignment \
  -H 'Authorization: Bearer YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "prospect_phone": "5559876543",
    "prospect_zip": "90210",
    "dialer_campaign": "9001",
    "real_time": false
  }'

Get Next ANI (Batch)

Section titled “Get Next ANI (Batch)”

Assigns ANIs for a batch of prospects in a single request. Useful for bulk list loading where many leads need an outbound caller ID at once. Each lead is processed independently — partial successes are reported per row.

  • Method: POST
  • URL: /assignment/batch
  • Headers:
    • Authorization: Bearer YOUR_API_KEY_HERE
    • Content-Type: application/json

Body Schema:

type Payload = {
  // Set to true for real-time / interactive assignment flows
  real_time?: boolean;


  // Set to true to return every assigned ANI in E.164 format. The calling code
  // is taken from each ANI's own area code, so the prefix is always correct for
  // the number returned. Applies to the whole batch. Defaults to false.
  e164?: boolean;


  // Array of leads to assign ANIs for
  leads: Array<{
    // Your identifier for this row — echoed back in the response
    row_id: string;


    // The prospect / customer phone number. 10-20 characters, so formatting
    // and a calling code are fine — both are stripped before matching.
    prospect_phone: string;


    // Optional US zip code for the prospect — improves geo-matching
    prospect_zip?: string;


    // The campaign identifier from your dialer platform (as saved in outboundIQ).
    // Optional if a default campaign is configured on your API key.
    dialer_campaign?: string;


    // Country to run this lead's selection in — 1 (US/Canada) or 44 (UK). Picks
    // the geo-matching rules and limits the result to that country's numbers.
    // Set per lead, so one batch can mix UK and US leads.
    country_code?: 1 | 44;
  }>;
};

Body Example:

{
  "real_time": false,
  "e164": false,
  "leads": [
    {
      "row_id": "lead-1",
      "prospect_phone": "5559876543",
      "prospect_zip": "90210",
      "dialer_campaign": "9001",
      "country_code": 1
    },
    {
      "row_id": "lead-2",
      "prospect_phone": "7700900123",
      "dialer_campaign": "9002",
      "country_code": 44
    },
    {
      "row_id": "lead-3",
      "prospect_phone": "5551234567",
      "prospect_zip": "10001",
      "dialer_campaign": "9001",
      "country_code": 1
    }
  ]
}

Success Response:

{
  "success": true,
  "results": [
    {
      "row_id": "lead-1",
      "outboundani": "2345678901",
      "error": ""
    },
    {
      "row_id": "lead-2",
      "outboundani": "7700900456",
      "error": ""
    },
    {
      "row_id": "lead-3",
      "outboundani": "",
      "error": "No available ANI found"
    }
  ]
}

Each entry in results corresponds to one lead from the request. A row is considered successful when error is empty; otherwise outboundani will be an empty string and error explains why.

With "e164": true, each outboundani is returned with its calling code prefixed — "+12345678901" for a US/Canada number, "+447700900456" for a UK number. The flag is set once for the whole request, not per lead.

Example

Section titled “Example”
Terminal window
curl -X POST \
  https://api.outboundiq.cloud/assignment/batch \
  -H 'Authorization: Bearer YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "real_time": false,
    "leads": [
      {
        "row_id": "lead-1",
        "prospect_phone": "5559876543",
        "prospect_zip": "90210",
        "dialer_campaign": "9001",
        "country_code": 1
      },
      {
        "row_id": "lead-2",
        "prospect_phone": "7700900123",
        "dialer_campaign": "9002",
        "country_code": 44
      }
    ]
  }'