Inbound Groups

Authentication

All API requests must include a universal API key as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Info

Your universal API key can be generated in the outboundIQ workspace dashboard. Create a new key of type universal and keep it secret — treat it like a password.

If the key is missing, invalid, inactive, or not a universal-typed key, the server will respond with a 401 or 403.

These endpoints are only available to workspaces with inbound groups enabled. Any other workspace receives a 422.

Base URL

https://api.outboundiq.cloud

Choosing an endpoint

• /inbound-group creates, edits, reads and deletes specific groups. It responds right away with the result for each group. Use it for targeted changes.
• /upload/inventory-groups takes a complete snapshot of every group and replaces the workspace’s groups and ANI inventory to match it. It is processed in the background. Use it for a full sync, for example a nightly export from your system.

Info

An inbound group is a named pool of ANIs, and one ANI can belong to many groups. Each group is identified by your own group_id.

Phone numbers are normalized to the bare 10-digit NANP number — formatting characters and a leading 1 are stripped, so "+1 (561) 123-4567" and "5611234567" are the same number. Duplicates within a group are ignored. Any phone that can’t be normalized, or whose area code can’t be resolved, rejects that group with a 400.

An ANI removed from its last group is marked removed from the dialer. Adding it to a group again brings it back.

Caution

A full snapshot upload replaces every group in the workspace, including groups created or edited through /inbound-group.

Endpoints

Create Group

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

Creates a group with the given phones. Phones not yet in your inventory are added to it. Returns 409 if the group already exists — use PUT to change it.

Body Schema:

type Group = {
  // Your identifier for the group
  group_id: string;
  // Display name
  group_name: string;
  // Every ANI in the group (at least one, up to 25,000)
  phones: string[];
};

// One group, or an array of up to 1,000 to create in one request
type Body = Group | Group[];

Body Example:

{
  "group_id": "g123",
  "group_name": "Florida Sales",
  "phones": ["5611234567", "3055550100"]
}

Success Response:

{
  "success": true,
  "group_id": "g123",
  "phones_added": 2,
  "anis_created": 1
}

Field	Description
phones_added	Phones added to the group
anis_created	Phones that were new to your inventory

Batch Body Example:

Each group_id may appear only once per request. Groups are created in order, and each one succeeds or fails on its own — a group with a bad phone or an existing group_id doesn’t stop the rest.

[
  {
    "group_id": "g123",
    "group_name": "Florida Sales",
    "phones": ["5611234567", "3055550100"]
  },
  {
    "group_id": "g456",
    "group_name": "Texas Sales",
    "phones": ["5611234567", "2145550100"]
  }
]

Batch Response:

A batch always responds with 200. The top-level success is true only when every group was created, and anis_created is the total for the request.

{
  "success": false,
  "anis_created": 2,
  "results": [
    {
      "success": true,
      "group_id": "g123",
      "phones_added": 2,
      "anis_created": 2
    },
    {
      "success": false,
      "group_id": "g456",
      "message": "Group already exists"
    }
  ]
}

Update Group

• Method: PUT
• URL: /inbound-group
• Headers:
  • Authorization: Bearer YOUR_API_KEY_HERE
  • Content-Type: application/json

Replaces the group’s name and its full phone list: phones you leave out are removed from the group. An ANI that is no longer in any group is removed from your inventory. Returns 404 for a group that doesn’t exist.

Body Schema:

type Group = {
  group_id: string;
  group_name: string;
  // The complete new phone list (at least one, up to 25,000)
  phones: string[];
};

// One group, or an array of up to 1,000 to update in one request
type Body = Group | Group[];

Body Example:

{
  "group_id": "g123",
  "group_name": "Florida Sales",
  "phones": ["5611234567", "7275550100"]
}

Success Response:

{
  "success": true,
  "group_id": "g123",
  "phones_added": 1,
  "phones_removed": 1,
  "anis_created": 1,
  "anis_removed": 1
}

Field	Description
phones_added	Phones added to the group
phones_removed	Phones taken out of the group
anis_created	Phones that were new to your inventory
anis_removed	ANIs removed from your inventory because they are no longer in any group

Batch Body Example:

Each group_id may appear only once per request. Groups are updated in order, and each one succeeds or fails on its own. A phone moved from one group to another in the same request stays in your inventory.

[
  {
    "group_id": "g123",
    "group_name": "Florida Sales",
    "phones": ["5611234567"]
  },
  {
    "group_id": "g456",
    "group_name": "Texas Sales",
    "phones": ["3055550100", "2145550100"]
  }
]

Batch Response:

A batch always responds with 200. The top-level success is true only when every group was updated. anis_created and anis_removed are totals for the request — anis_removed is only reported here, because an ANI is removed only once every group in the request has been applied.

{
  "success": true,
  "anis_created": 0,
  "anis_removed": 0,
  "results": [
    {
      "success": true,
      "group_id": "g123",
      "phones_added": 0,
      "phones_removed": 1,
      "anis_created": 0
    },
    {
      "success": true,
      "group_id": "g456",
      "phones_added": 1,
      "phones_removed": 1,
      "anis_created": 0
    }
  ]
}

Get Group

• Method: GET
• URL: /inbound-group?group_id=GROUP_ID

Query Params:

Name	Type	Description
group_id	string	Your identifier for the group

Example:

GET /inbound-group?group_id=g123

Success Response:

{
  "success": true,
  "group": {
    "group_id": "g123",
    "group_name": "Florida Sales",
    "phones": ["3055550100", "5611234567"]
  }
}

Delete Group

• Method: DELETE
• URL: /inbound-group
• Headers:
  • Authorization: Bearer YOUR_API_KEY_HERE
  • Content-Type: application/json

Removes every phone from the group and deletes the group. ANIs that are no longer in any group are removed from your inventory. Returns 404 for a group that doesn’t exist. You can create a deleted group again later with POST.

Body Schema:

type Group = {
  group_id: string;
};

// One group, or an array of up to 1,000 to delete in one request
type Body = Group | Group[];

Body Example:

{ "group_id": "g123" }

Success Response:

{ "success": true, "group_id": "g123", "anis_removed": 1 }

anis_removed counts ANIs that were only in this group and have now been removed from your inventory. Phones that are still in another group stay in your inventory.

Batch Body Example:

Each group_id may appear only once per request. Groups are deleted in order, and each one succeeds or fails on its own — a group_id that doesn’t exist doesn’t stop the rest.

[{ "group_id": "g123" }, { "group_id": "g456" }]

Batch Response:

A batch always responds with 200. The top-level success is true only when every group was deleted. anis_removed is the total for the request, counting ANIs that are in none of the remaining groups once every deletion has been applied.

{
  "success": true,
  "anis_removed": 3,
  "results": [
    { "success": true, "group_id": "g123" },
    { "success": true, "group_id": "g456" }
  ]
}

Replace All Groups

• Method: POST
• URL: /upload/inventory-groups
• Headers:
  • Authorization: Bearer YOUR_API_KEY_HERE
  • Content-Type: application/json

Uploads a complete snapshot of every group in the workspace. The workspace’s groups, ANI inventory and group memberships are rebuilt to match it.

The body is checked as soon as it arrives, then processed in the background. Progress and the final result appear on the Inbound Groups page in the workspace, alongside uploads made there. It is safe to send during calling hours: new memberships are written before old ones are removed, so a group is never left without ANIs.

Caution

The snapshot replaces everything. Groups missing from it are deleted, and ANIs missing from it are marked removed from the dialer. An ANI dropped from one group but still listed in another keeps working. Always send a complete snapshot, never a partial one.

Unlike /inbound-group, a snapshot doesn’t reject bad data. Phones that can’t be normalized or whose area code can’t be resolved are skipped, as are groups with an empty group_id or one longer than 255 characters. A snapshot with no groups is refused and changes nothing. The body can be up to 100 MB, and a UTF-8 byte order mark is accepted.

Body Schema:

type Group = {
  // Your identifier for the group
  group_id: string;
  // Display name (defaults to group_id when blank)
  group_name: string;
  // Every ANI in the group
  phones: string[];
};

// Every group in the workspace
type Body = Group[];

Body Example:

[
  {
    "group_id": "g123",
    "group_name": "Florida Sales",
    "phones": ["5611234567", "3055550100"]
  },
  {
    "group_id": "g456",
    "group_name": "Texas Sales",
    "phones": ["5611234567", "2145550100"]
  }
]

Success Response (202 Accepted):

{ "success": true, "uploadId": 4821 }

A body that isn’t valid JSON or doesn’t match the schema is rejected with a 400. A body over 100 MB is rejected with a 413.