---
title: "Register for a new callback type"
method: POST
path: "/companies/{company_key}/config/callbacks/"
tags: ["Callback API"]
---

# Register for a new callback type

`POST /companies/{company_key}/config/callbacks/`

## Path parameters

- `company_key` string, required

## Headers

- `X-API-Version` string
- `Content-Type` string, required

## Request body

- union
  - CallbackRequestAck
    - `callback_type` 'ack_participant_added' | 'ack_participant_changed' | 'company_participant_added' | 'company_participant_changed', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `ack_participant_changed` object — Required for Acquisition Changed callback.
      - `campaign_id` string — Vibes unique identifier for an acquisition campaign.
    - `ack_participant_added` object — Required for Acquisition Added callback.
      - `campaign_id` string — Vibes unique identifier for an acquisition campaign.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestEvent
    - `callback_type` 'event_processed', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `event_processed` object, required
      - `event_type` string — The name of the event that you would like to receive callbacks for.
      - `callbacks_to_send` 'all' | 'only_failures' | 'routing' | 'carrier_dlr' | 'handset_dlr' — Choose which callbacks you'd like to receive. Default is all.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestPerson
    - `callback_type` 'person_added' | 'person_updated', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestPush
    - `callback_type` 'device_added' | 'device_removed' | 'device_updated', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `device_added` object — Required for Push Device Added callback.
      - `app_id` string — Your push application id.
    - `device_removed` object — Required for Push Device Removed callback.
      - `app_id` string — Your push application id.
    - `device_updated` object — Required for Push Device Updated callback.
      - `app_id` string — Your push application id.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestSub
    - `callback_type` 'subscription_added' | 'subscription_removed', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `subscription_added` object — Required for Subscription Added callback.
      - `list_id` string — Vibes unique identifier for a subscription list.
    - `subscription_removed` object — Required for Subscription Removed callback.
      - `list_id` string — Vibes unique identifier for a subscription list.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestSubList
    - `callback_type` 'subscription_list_added' | 'subscription_list_updated', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestUnmatched
    - `callback_type` 'unmatched_message_received', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `unmatched_message_received` object, required — Required for Unmatched Message callback.
      - `source_code` string, required — The short code, long code, or alpha code you want to receive unmatched message events for.
      - `country_code` string — The country code for the source code you want to receive unmatched message events for.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.
  - CallbackRequestWallet
    - `callback_type` 'wallet_item_install' | 'wallet_item_remove', required — The type of callback to register.
    - `destination` object, required
      - `url` string, required — External URL to submit the callback data.
      - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
      - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
    - `wallet_item_install` object — Required for Wallet Item Install callback.
      - `campaign_token` string — The campaign token for the wallet campaign.
    - `wallet_item_remove` object — Required for Wallet Item Remove callback.
      - `campaign_token` string — The campaign token for the wallet campaign.
    - `start_date` string — Date you’d like to start receiving this callback in ISO-8601 format. Leave blank to start immediately.
    - `end_date` string — Date you’d like to stop receiving this callback in ISO-8601 format. Leave blank for no end date.

## Response `200`

Successful response

- CallbackResponse
  - `callback_id` string — Vibes unique identifier for each callback record.
  - `callback_type` string — Callback type to trigger this callback.
  - `ack_participant_changed` object — Present for Acquisition Changed callback.
    - `campaign_id` string — Vibes unique identifier for an acquisition campaign.
  - `ack_participant_added` object — Present for Acquisition Added callback.
    - `campaign_id` string — Vibes unique identifier for an acquisition campaign.
  - `subscription_added` object — Present for Subscription Added callback.
    - `list_id` string — Vibes unique identifier for a subscription list.
  - `subscription_removed` object — Present for Subscription Removed callback.
    - `list_id` string — Vibes unique identifier for a subscription list.
  - `unmatched_message_received` object — Present for Unmatched Message callback.
    - `source_code` string — The short code, long code, or alpha code you want to receive unmatched message events for.
    - `country_code` string — The country code for the source code you want to receive unmatched message events for.
  - `wallet_item_install` object — Present for Wallet Item Install callback.
    - `campaign_token` string — The campaign token for the wallet campaign.
  - `wallet_item_remove` object — Present for Wallet Item Removed callback.
    - `campaign_token` string — The campaign token for the wallet campaign.
  - `device_added` object — Present for Push Device Added callback.
    - `app_id` string — Your push application id.
  - `device_removed` object — Present for Push Device Removed callback.
    - `app_id` string — Your push application id.
  - `device_updated` object — Present for Push Device Updated callback.
    - `app_id` string — Your push application id.
  - `event_processed` object — Present for event-triggered callback if you only want to recieve callbacks for a single event.
    - `event_type` string
    - `callbacks_to_send` 'all' | 'only_failures' | 'routing' | 'carrier_dlr' | 'handset_dlr' — Choose which callbacks you'd like to receive. Default is all.
  - `destination` object
    - `url` string — External URL to submit the callback data.
    - `method` 'POST' | 'PUT' — Method to submit the data to the destination URL.
    - `content_type` 'application/json' | 'text/json' — Content type to set when submitting the data to the destination URL.
  - `start_date` string — The date the campaign is starting in ISO-8601 format.
  - `end_date` string — The date the Campaign is ending in ISO-8601 format.
  - `url` string — Unique resource URL for the callback.
  - `created_date` string — The date the campaign was created in ISO-8601 format.
  - `updated_date` string — The date the campaign was last updated in ISO-8601 format.

## Other responses

- `201` — Callback has been successfully registered.

---

[API](https://skmtc.net/vibes/apis/vibes-platform-api.md) · [All operations](https://skmtc.net/vibes/apis/vibes-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vibes/vibes-platform-api/revisions/2d5797ce1b84/schema)