We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

Events

Events that can be sent from the system to a configured event subscription.

See Event Subscriptions for details on registering your own subscription to receive these events.

Events are sent during the processing of a request, typically they are sent when:

  • An order is completed (whether successful or failure)
  • A request is completed (whether successful or failure)
  • When a DID is created via request
  • When a DID is deleted via request
  • When a DID has a feature added (i.e. messaging, csp campaign, etc...)
  • When a DID has a feature removed (i.e. messaging, csp campaign, etc...)

More events may be added in the future as needed.

Schema

Format of the Subscription Event webhook.

Type Object

Name Type Description
associations associations Desc. associations
data One-Of
id String(format:ulid) Desc. id
inserted_at String(format:date-time) Desc. inserted_at
timestamp String(format:date-time) Desc. timestamp
topic SystemEventTopic
type SystemEventType

Desc. associations

Depending on the type, this field will contain additional associations of the parent record.

For example:

  • ORDER_COMPLETED - will include requests
  • REQUEST_COMPLETED - will include provision_records

One-Of

Types

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. inserted_at

When was this event first created?

Desc. timestamp

When was the event sent from the host system?

associations

Name Type Description
provision_records Array:SystemEventAssociationProvisionRecord
requests Array:SystemEventAssociationRequest

Example

{
  "associations": {
    "provision_records": [
      {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "number": "12003004000",
        "status": "NONE"
      }
    ],
    "requests": [
      {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "status": "NEW"
      }
    ]
  },
  "data": {
    "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "tcr_campaign_id": "C000000"
  },
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "timestamp": "2021-08-13T04:08:44.762841Z",
  "topic": "NONE",
  "type": "DID_CREATED"
}

Request

Event Subscriptions control the request that will be made to the endpoint, while multiple protocols are listed, only HTTP is fully supported.

Requests will be retried up to 17 times of the course of 3 days.

The webhook system will accept any 2xx status as a success.

It is recommended that a 204 No Content be returned while using the event subscription in case a response is supported by the webhook later.

Types

CSP Campaign Registered

Schema

CSP_CAMPAIGN_REGISTERED

Type Object

Name Type Description
csp_campaign_id String(format:ulid) Desc. csp_campaign_id
tcr_campaign_id String The TCR issued campaign ID

Desc. csp_campaign_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "tcr_campaign_id": "C000000"
}

CSP Campaign - Optout Item - Created

Schema

CSP_CAMPAIGN_OPTOUT_ITEM_CREATED

The creation of an optout item is the explicit action of a subscriber opting out of receiving messages.

Type Object

Name Type Description
csp_campaign_id String(format:ulid) Desc. csp_campaign_id
host_number String Desc. host_number
keyword String Desc. keyword
remote_number String Desc. remote_number
tcr_campaign_id String The TCR issued campaign ID

Desc. csp_campaign_id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. keyword

If the optout was triggered by the system, this field will be populated with the keyword used.

Will be some variant of STOP normally.

For more information about keywords and their handling, contact support.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Example

{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001",
  "tcr_campaign_id": "C000000"
}

CSP Campaign - Optout Item - Deleted

Schema

CSP_CAMPAIGN_OPTOUT_ITEM_DELETED

While it may be confusing at first, the deletion of an optout item signifies that a subscriber, as opted-in to receive messages and a restriction is no longer in place.

Type Object

Name Type Description
csp_campaign_id String(format:ulid) Desc. csp_campaign_id
host_number String Desc. host_number
keyword String Desc. keyword
remote_number String Desc. remote_number
tcr_campaign_id String The TCR issued campaign ID

Desc. csp_campaign_id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. keyword

If the optout was triggered by the system, this field will be populated with the keyword used.

Will be some variant of STOP normally.

For more information about keywords and their handling, contact support.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Example

{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001",
  "tcr_campaign_id": "C000000"
}

DID Component Created

Schema

DID_COMPONENT_CREATED

Type Object

Name Type Description
component SystemEventDataDidComponent
did_id String(format:uuid) Desc. did_id
number String Desc. number
reason SystemEventDataDidCreatedReason
request_id String(format:ulid) Desc. request_id

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. request_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "component": "UNKNOWN",
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}

DID Component Deleted

Schema

DID_COMPONENT_DELETED

Type Object

Name Type Description
component SystemEventDataDidComponent
did_id String(format:uuid) Desc. did_id
number String Desc. number
reason SystemEventDataDidDeletedReason
request_id String(format:ulid) Desc. request_id

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. request_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "component": "UNKNOWN",
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}

DID Created

Schema

DID_CREATED

Type Object

Name Type Description
did_id String(format:uuid) Desc. did_id
number String Desc. number
reason SystemEventDataDidCreatedReason
request_id String(format:ulid) Desc. request_id

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. request_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}

DID Deleted

Schema

DID_DELETED

Type Object

Name Type Description
did_id String(format:uuid) Desc. did_id
number String Desc. number
reason SystemEventDataDidDeletedReason
request_id String(format:ulid) Desc. request_id

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. request_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}

DID - Optout Item - Created

Schema

DID_OPTOUT_ITEM_CREATED

The creation of an optout item is the explicit action of a subscriber opting out of receiving messages.

Type Object

Name Type Description
host_did_id String(format:uuid) Desc. host_did_id
host_number String Desc. host_number
keyword String Desc. keyword
remote_number String Desc. remote_number

Desc. host_did_id

A Universally unique identifier, which identifies the resource

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. keyword

If the optout was triggered by the system, this field will be populated with the keyword used.

Will be some variant of STOP normally.

For more information about keywords and their handling, contact support.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Example

{
  "host_did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001"
}

DID - Optout Item - Deleted

Schema

DID_OPTOUT_ITEM_DELETED

While it may be confusing at first, the deletion of an optout item signifies that a subscriber, as opted-in to receive messages and a restriction is no longer in place.

Type Object

Name Type Description
host_did_id String(format:uuid) Desc. host_did_id
host_number String Desc. host_number
keyword String Desc. keyword
remote_number String Desc. remote_number

Desc. host_did_id

A Universally unique identifier, which identifies the resource

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. keyword

If the optout was triggered by the system, this field will be populated with the keyword used.

Will be some variant of STOP normally.

For more information about keywords and their handling, contact support.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Example

{
  "host_did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001"
}

Order Completed

Schema

ORDER_COMPLETED

This event is sent whenever an ORDER is considered complete, not necessarily COMPLETED.

The requests associations will be included in the parent System Event.

Note the requests association do not include their PVRs, you must have the REQUEST topic enabled to receive those details.

Type Object

Name Type Description
error_code OrderErrorCode
order_id String(format:ulid) Desc. order_id
status OrderStatus

Desc. order_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "error_code": "OK",
  "order_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "status": "NEW"
}

Request Completed

Schema

REQUEST_COMPLETED

This event is sent whenever a REQUEST is considered complete (not necessarily COMPLETED, it may be an ERROR as well).

The parent System Event will contain the provision_records associations which give a finer detail of what specific items were completed or had errors.

Type Object

Name Type Description
data One-Of
error_code OrderErrorCode
order_id String(format:ulid) Desc. order_id
request_id String(format:ulid) Desc. request_id
status OrderStatus
type RequestType

One-Of

Types

Desc. order_id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. request_id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "data": {
    "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "tcr_brand_id": "B123456"
  },
  "error_code": "OK",
  "order_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "status": "NEW",
  "type": "ADD_CAMPAIGN_NUMBERS"
}

OSR Overwrite Request Pending

Schema

OSR_OVERWRITE_REQUEST_PENDING

Type Object

Name Type Description
did_id String(format:uuid) Desc. did_id
error_code Enum(OK):String Further explanation of an error status
new_nnid_service_provider String
number String Desc. number
osr_overwrite_request_id String(format:ulid) Desc. osr_overwrite_request_id
review_status Enum:String Desc. review_status
status Enum:String Desc. status

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. osr_overwrite_request_id

Another format for UUID, used primarily for tasks, requests and messages.

Enum Values review_status

Allowed values

  • NONE
  • APPROVED
  • REJECTED
  • AUTO_APPROVED
  • AUTO_REJECTED
  • FORCE_DELETED

Desc. review_status

The review status of the request, defaults to NONE.

Enum Values status

Allowed values

  • NEW
  • REVIEWED
  • APPROVED
  • REJECTED
  • ERROR
  • STALE
  • DELETED

Desc. status

The current processing status of the request

Example

{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "error_code": "OK",
  "new_nnid_service_provider": "ACME Corp",
  "number": "12003004000",
  "osr_overwrite_request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "review_status": "NONE",
  "status": "NEW"
}

OSR Overwrite Request Completed

Schema

OSR_OVERWRITE_REQUEST_COMPLETED

Type Object

Name Type Description
did_id String(format:uuid) Desc. did_id
error_code Enum(OK):String Further explanation of an error status
new_nnid_service_provider String
number String Desc. number
osr_overwrite_request_id String(format:ulid) Desc. osr_overwrite_request_id
review_status Enum:String Desc. review_status
status Enum:String Desc. status

Desc. did_id

A Universally unique identifier, which identifies the resource

Desc. number

The 3 to 15 digit code of the number.

Desc. osr_overwrite_request_id

Another format for UUID, used primarily for tasks, requests and messages.

Enum Values review_status

Allowed values

  • NONE
  • APPROVED
  • REJECTED
  • AUTO_APPROVED
  • AUTO_REJECTED
  • FORCE_DELETED

Desc. review_status

The review status of the request, defaults to NONE.

Enum Values status

Allowed values

  • NEW
  • REVIEWED
  • APPROVED
  • REJECTED
  • ERROR
  • STALE
  • DELETED

Desc. status

The current processing status of the request

Example

{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "error_code": "OK",
  "new_nnid_service_provider": "ACME Corp",
  "number": "12003004000",
  "osr_overwrite_request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "review_status": "NONE",
  "status": "NEW"
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.