# Sinch Engage — Full Reference > Complete Markdown content of every production-relevant documentation page, inlined for single-fetch AI consumption. Auto-generated on every docs publish. ### Source: docs/api/account-management/create-customer-subaccount.md # Create a sub-account Create a new sub-account so it can start sending messages from Sinch Engage. Include `user.email` to add an initial admin user. If `user.email` is omitted or empty, the sub-account is still created with zero users. Each of the following account properties is required: - `company_name`: A human-readable name for the sub-account that appears as the account name in the Sinch Engage web portal. - `timezone`: Time zone for the account. Time zones are used to present datetime in local time in the Sinch Engage web portal and in any reports. Time zones must be in IANA format. For example `Australia/Melbourne`, `Pacific/Auckland`. - `operating_country`: The primary country the account will send messages to. Use one of `AU`, `NZ`, `UK`, or `US`. - `billing_type`: Always set to `POSTPAID` for this API. - `user`: Details of the initial admin user on the sub-account. Include `user.email` to create that user. If `user.email` matches an existing platform user, they are added to the account and sent an invitation email. If the email is new, they receive a welcome email with an activation link. If `user.email` is omitted or empty, the sub-account is still created with **zero users** — a user is not created without an email. | | | |---|---| | **Service** | [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/reseller_customers` | | **Operation ID** | `CreateCustomerSubaccount` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Account` | string | No | The account the new sub-account will be created under (its parent). Leave this out to create it directly under your own account (the account your API key belongs to). Set it to nest further down under any account you already manage; naming an account you do not manage is rejected. Example: `TestAccount_ABC_0001` | ## Request body JSON object describing the sub-account and initial admin user. | Field | Type | Required | Description | |-------|------|----------|-------------| | `company_name` | string | Yes | Company name. Cannot contain the `./` substring. Length 2–200. Used to generate an account unique identifier. | | `timezone` | string | Yes | IANA time zone name used for Sinch Engage and reports, for example `Australia/Melbourne`. Time zones must be in IANA format. | | `operating_country` | string | Yes | One of `AU`, `NZ`, `UK`, or `US`. | | `billing_type` | string | Yes | Always set to `POSTPAID`. | | `user` | object | Yes | Initial admin user. Include `user.email` to create that user. | | `user.first_name` | string | Yes | First name. Length 1–40. Cannot have more than one sequential space. | | `user.last_name` | string | Yes | Last name. Length 1–80. Cannot have more than one sequential space. | | `user.email` | string | No | Sinch Engage login address. If omitted or empty, the sub-account is still created with zero users. A user is not created without an email. | | `user.phone` | string | Yes | The user's phone number. This must be in E.164 format (for example `+61412345678`). | ## Responses | Status | Description | |--------|-------------| | 201 | Customer subaccount created | | 400 | Request parameter is invalid | | 401 | No valid authentication details were provided | | 404 | Not found | | 500 | Server error | ### 201 response ```json { "parent_account": "TestAccount_ABC_0001", "account_id": "TestAccount_ABC_0002" } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/iam/reseller_customers" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Account: TestAccount_ABC_0001" \ -d '{ "company_name": "Subaccount Name", "timezone": "Australia/Melbourne", "operating_country": "AU", "billing_type": "POSTPAID", "user": { "first_name": "First", "last_name": "Last", "email": "first.last@email.com", "phone": "+61411111111" } }' ``` [← Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) --- ### Source: docs/api/account-management/create-users-for-account.md # Create users for an account Create additional users in the web portal. New users receive an activation email to finish setting up their user profile. For existing users (matched by email address) this adds the user to the specified account and sends an invitation email the user must accept in order to use the account in Sinch Engage. This endpoint requires you to handle both success statuses: **201** when a user is created or newly invited (response body includes `email`), and **204** when that email already has access to the account (already a member, or already invited). | | | |---|---| | **Service** | [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/accounts/{id}/users` | | **Operation ID** | `CreateUserForAccount` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | Yes | Account id to create a user for. Example: `MyTestAccount_ZQR_0001` | ### Query parameters None. ### Header parameters None. ## Request body | Field | Type | Required | Description | |-------|------|----------|-------------| | `email` | string | Yes | Email address of the user to create or add. | ## Responses | Status | Description | |--------|-------------| | 201 | A new user was invited. Body includes the email that was invited. | | 204 | That email already has access to this account (already a member, or already has an invite). Empty body. | | 400 | Request parameter is invalid | | 401 | No valid authentication details were provided | | 404 | The account does not exist, or you cannot manage it | | 500 | Server error | ### 201 response ```json { "email": "first.last@email.com" } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/iam/accounts/MyTestAccount_ZQR_0001/users" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"email":"first.last@email.com"}' ``` [← Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) --- ### Source: docs/api/account-management/delete-customer-account.md # Delete a sub-account Permanently deletes the sub-account named in `{id}`. This does **not** delete your own (parent) account. `{id}` must be a sub-account you manage. This cannot be undone. - Sinch Engage users on that sub-account will no longer be able to use it. - The sub-account can no longer send or receive messages. - Any sub-accounts nested under it are also deleted. A successful delete returns **204** with an empty body. If the account does not exist or you cannot manage it, the API returns **404**. | | | |---|---| | **Service** | [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/accounts/{id}` | | **Operation ID** | `DeleteCustomerAccount` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | Yes | The sub-account to delete. Must be a sub-account you manage. Example: `MyTestAccount_ZQR_0001` | ### Query parameters None. ### Header parameters None. ## Responses | Status | Description | |--------|-------------| | 204 | The sub-account was deleted. Empty body. | | 401 | The request was not authenticated. Check your API key (or username and password). | | 404 | The account in `{id}` does not exist, or you do not have permission to delete it. Both cases return 404 so callers cannot tell them apart. | | 500 | Server error | ### 204 response No response body is returned on successful deletion. ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/iam/accounts/MyTestAccount_ZQR_0001" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" ``` [← Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) --- ### Source: docs/api/account-management/index.md # Account Management The Account Management API is for **reseller** accounts. It allows resellers to add and remove sub-accounts on their primary Sinch Engage account, and to manage Sinch Engage web portal users for those accounts. This is distinct from sending messages *on behalf of* an existing sub-account, which uses the `Account` header described in the [Sub-accounts](https://developers.app.sinch.com/docs/guides/sub-accounts.md) guide. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Create a sub-account with an initial admin user | [Create a sub-account](https://developers.app.sinch.com/docs/api/account-management/create-customer-subaccount.md) | | Add a Sinch Engage user to an existing account | [Create users for an account](https://developers.app.sinch.com/docs/api/account-management/create-users-for-account.md) | | Delete a sub-account | [Delete a sub-account](https://developers.app.sinch.com/docs/api/account-management/delete-customer-account.md) | ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Create a sub-account](https://developers.app.sinch.com/docs/api/account-management/create-customer-subaccount.md) | `POST` | `/v1/iam/reseller_customers` | Create a new sub-account with an initial admin user | | [Create users for an account](https://developers.app.sinch.com/docs/api/account-management/create-users-for-account.md) | `POST` | `/v1/iam/accounts/{id}/users` | Add a Sinch Engage user to an existing account | | [Delete a sub-account](https://developers.app.sinch.com/docs/api/account-management/delete-customer-account.md) | `DELETE` | `/v1/iam/accounts/{id}` | Permanently delete a sub-account | ## Specification details These APIs are for **reseller accounts only**. That is how they work today. They are not documented for every account type. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/contacts/add-contact-to-contact-list.md # Add contact to a list Adds a contact to a contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}/contacts/{contactId}` | | **Operation ID** | `addContactToContactList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Contacts have been added | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | | `contactId` | string (uuid) | Yes | Contact id to remove in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Contacts have been added | `ListData` | | 201 | Created | `ListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 and 201 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | List id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `name` | string | Yes | List name | | `alias` | string | Yes | List alias | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts/4a03d2d8-1f85-463f-bdb4-2891c17258a7" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts/4a03d2d8-1f85-463f-bdb4-2891c17258a7", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/create-contact-list.md # Create a contact list Creates a new contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists` | | **Operation ID** | `createContactList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Contact list is created | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | Yes | Group name | | `alias` | string | No | Group alias | ### Example request body ```json { "name": "My group", "alias": "Group1" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Contact list is created | `ListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 201 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | List id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `name` | string | Yes | List name | | `alias` | string | Yes | List alias | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/api/v1/contacts/lists" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name": "My group", "alias": "Group1" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "My group", "alias": "Group1" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) - [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/create-contact.md # Create a contact Creates a new contact in the account. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/contacts` | | **Operation ID** | `createContact` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Contact is created | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `firstName` | string | No | Contact first name | | `lastName` | string | No | Contact last name | | `alias` | string | No | Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms | | `dateOfBirth` | string (date) | No | Date of birth | | `country` | string | No | Country | | `state` | string | No | State | | `location` | string | No | Location | | `note` | string | No | Note | | `channels` | array of object | Yes | Contact channels | | `channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `channels[].type` | string; enum: `SMS`, `WHATSAPP` | Yes | Contact channel type | | `channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `lists` | array of object | No | Contact lists | | `lists[].id` | string (uuid) | Yes | List id in UUID format | | `customFields` | array of object | No | Contact custom fields | | `customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `customFields[].value` | string | Yes | Custom field value | ### Example request body ```json { "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Contact is created | `ContactData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 201 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Contact id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `firstName` | string | Yes | Contact first name | | `lastName` | string | Yes | Contact last name | | `fullName` | string | Yes | Contact full name | | `alias` | string | Yes | Contact alias | | `dateOfBirth` | string (date) | No | Date of birth | | `country` | string | Yes | Country | | `state` | string | Yes | State | | `location` | string | Yes | Location | | `note` | string | Yes | Note | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | | `customFields` | array of object | Yes | List of custom fields | | `customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `customFields[].mergeTag` | string | Yes | Custom field merge tag | | `customFields[].value` | string | Yes | Custom field value | | `customFields[].type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `channels` | array of object | Yes | Contact channels | | `channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `channels[].type` | string; enum: `SMS`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | Yes | Contact channel type | | `channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `lists` | array of object | Yes | Contact lists | | `lists[].id` | string (uuid) | Yes | List id in UUID format | | `lists[].name` | string | Yes | List name | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/api/v1/contacts/contacts" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/contacts", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) - [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) - [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) - [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/create-custom-field.md # Create a custom field Creates a new custom field for contacts. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/custom-fields` | | **Operation ID** | `createCustomField` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Custom field is created | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `label` | string | Yes | Custom field label | | `mergeTag` | string | Yes | Custom field merge tag | | `maxLength` | integer (int32) | Yes | Custom field max length | | `type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | ### Example request body ```json { "label": "Contact name", "mergeTag": "contact_name", "maxLength": 30, "type": "DATE" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Custom field is created | `CustomFieldData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 201 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Custom field id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `label` | string | Yes | Custom field label | | `mergeTag` | string | Yes | Custom field merge tag | | `maxLength` | integer (int32) | Yes | Custom field max length | | `type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/api/v1/contacts/custom-fields" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Contact name", "mergeTag": "contact_name", "maxLength": 30, "type": "DATE" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/custom-fields", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "label": "Contact name", "mergeTag": "contact_name", "maxLength": 30, "type": "DATE" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) - [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) - [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) - [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/delete-contact-by-id.md # Delete a contact Deletes a contact from the account. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/contacts/{contactId}` | | **Operation ID** | `deleteContactById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — Contact is deleted | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `contactId` | string (uuid) | Yes | Contact id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | Contact is deleted | — | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) - [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) - [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) - [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/delete-contact-list-by-id.md # Delete a contact list Deletes a contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}` | | **Operation ID** | `deleteContactListById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — Contact list is deleted | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | Contact list is deleted | — | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/delete-custom-field-by-id.md # Delete a custom field Deletes a custom field. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/{customFieldId}` | | **Operation ID** | `deleteCustomFieldById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — Custom field is deleted | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customFieldId` | string (uuid) | Yes | Custom field id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | Custom field is deleted | — | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) - [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) - [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) - [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-contact-by-id.md # Get a single contact Retrieves details for a single contact by ID. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/contacts/{contactId}` | | **Operation ID** | `getContactById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a single contact | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `contactId` | string (uuid) | Yes | Contact id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a single contact | `ContactData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Contact id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `firstName` | string | Yes | Contact first name | | `lastName` | string | Yes | Contact last name | | `fullName` | string | Yes | Contact full name | | `alias` | string | Yes | Contact alias | | `dateOfBirth` | string (date) | No | Date of birth | | `country` | string | Yes | Country | | `state` | string | Yes | State | | `location` | string | Yes | Location | | `note` | string | Yes | Note | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | | `customFields` | array of object | Yes | List of custom fields | | `customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `customFields[].mergeTag` | string | Yes | Custom field merge tag | | `customFields[].value` | string | Yes | Custom field value | | `customFields[].type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `channels` | array of object | Yes | Contact channels | | `channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `channels[].type` | string; enum: `SMS`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | Yes | Contact channel type | | `channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `lists` | array of object | Yes | Contact lists | | `lists[].id` | string (uuid) | Yes | List id in UUID format | | `lists[].name` | string | Yes | List name | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) - [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) - [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) - [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-contact-list-by-id.md # Get a single contact list Retrieves details for a single contact list by ID. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}` | | **Operation ID** | `getContactListById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a single contact list | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a single contact list | `ListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | List id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `name` | string | Yes | List name | | `alias` | string | Yes | List alias | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) - [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-contact-lists-page.md # Get contact lists page Retrieves a paginated list of contact lists. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists` | | **Operation ID** | `getContactListsPage` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a contact lists page | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `request` | object | Yes | Pagination and filter options for the contact lists page (page tokens, page size, and related filters).
| #### `request` fields | Property | Type | Required | Description | |----------|------|----------|-------------| | `nextPageToken` | string | No | | | `prevPageToken` | string | No | | | `pageSize` | integer (int32); maximum: 1000 | No | | | `listIds` | array of string (uuid) | No | | | `alias` | string | No | | | `name` | string | No | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a contact lists page | `PageTokenDtoListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `content` | array of object | Yes | Page content and number of elements is restricted by page size | | `content[].id` | string (uuid) | Yes | List id in UUID format | | `content[].accountId` | string | Yes | Account id | | `content[].vendorId` | string | Yes | Vendor id | | `content[].name` | string | Yes | List name | | `content[].alias` | string | Yes | List alias | | `content[].createdDate` | string (date-time) | Yes | Create date | | `content[].lastModifiedDate` | string (date-time) | Yes | Last modified date | | `nextPageToken` | string | No | Pagination token to retrieve the next page | | `prevPageToken` | string | No | Pagination token to retrieve the previous page | | `totalElements` | integer (int64) | Yes | Total number of elements | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/lists?pageSize=1" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists?pageSize=1", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) - [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-contacts-page.md # Get contacts page Retrieves a paginated list of contacts. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/contacts` | | **Operation ID** | `getContactsPage` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a contacts page | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `request` | object | Yes | Pagination and filter options for the contacts page (page tokens, page size, list/contact/channel filters).
| #### `request` fields | Property | Type | Required | Description | |----------|------|----------|-------------| | `nextPageToken` | string | No | | | `prevPageToken` | string | No | | | `pageSize` | integer (int32); maximum: 1000 | No | | | `listIds` | array of string (uuid) | No | | | `contactIds` | array of string (uuid) | No | | | `channelIds` | array of string | No | | | `channelTypes` | array of string; enum: `SMS`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | | | `channelSubscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a contacts page | `PageTokenDtoContactData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `content` | array of object | Yes | Page content and number of elements is restricted by page size | | `content[].id` | string (uuid) | Yes | Contact id in UUID format | | `content[].accountId` | string | Yes | Account id | | `content[].vendorId` | string | Yes | Vendor id | | `content[].firstName` | string | Yes | Contact first name | | `content[].lastName` | string | Yes | Contact last name | | `content[].fullName` | string | Yes | Contact full name | | `content[].alias` | string | Yes | Contact alias | | `content[].dateOfBirth` | string (date) | No | Date of birth | | `content[].country` | string | Yes | Country | | `content[].state` | string | Yes | State | | `content[].location` | string | Yes | Location | | `content[].note` | string | Yes | Note | | `content[].createdDate` | string (date-time) | Yes | Create date | | `content[].lastModifiedDate` | string (date-time) | Yes | Last modified date | | `content[].customFields` | array of object | Yes | List of custom fields | | `content[].customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `content[].customFields[].mergeTag` | string | Yes | Custom field merge tag | | `content[].customFields[].value` | string | Yes | Custom field value | | `content[].customFields[].type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `content[].channels` | array of object | Yes | Contact channels | | `content[].channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `content[].channels[].type` | string; enum: `SMS`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | Yes | Contact channel type | | `content[].channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `content[].lists` | array of object | Yes | Contact lists | | `content[].lists[].id` | string (uuid) | Yes | List id in UUID format | | `content[].lists[].name` | string | Yes | List name | | `nextPageToken` | string | No | Pagination token to retrieve the next page | | `prevPageToken` | string | No | Pagination token to retrieve the previous page | | `totalElements` | integer (int64) | Yes | Total number of elements | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/contacts?pageSize=1" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/contacts?pageSize=1", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) - [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) - [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) - [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-custom-field-by-id.md # Get a single custom field Retrieves details for a single custom field by ID. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/{customFieldId}` | | **Operation ID** | `getCustomFieldById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a single custom field | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customFieldId` | string (uuid) | Yes | Custom field id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a single custom field | `CustomFieldData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Custom field id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `label` | string | Yes | Custom field label | | `mergeTag` | string | Yes | Custom field merge tag | | `maxLength` | integer (int32) | Yes | Custom field max length | | `type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) - [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) - [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) - [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/get-custom-fields-page.md # Get custom fields page Retrieves a paginated list of custom fields. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/custom-fields` | | **Operation ID** | `getCustomFieldsPage` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Returns a custom fields page | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `request` | object | Yes | Pagination and filter options for the custom fields page (page tokens, page size, and related filters).
| #### `request` fields | Property | Type | Required | Description | |----------|------|----------|-------------| | `nextPageToken` | string | No | | | `prevPageToken` | string | No | | | `pageSize` | integer (int32); maximum: 1000 | No | | | `customFieldIds` | array of string (uuid) | No | | | `label` | string | No | | | `mergeTag` | string | No | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Returns a custom fields page | `PageTokenDtoCustomFieldData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `content` | array of object | Yes | Page content and number of elements is restricted by page size | | `content[].id` | string (uuid) | Yes | Custom field id in UUID format | | `content[].accountId` | string | Yes | Account id | | `content[].vendorId` | string | Yes | Vendor id | | `content[].label` | string | Yes | Custom field label | | `content[].mergeTag` | string | Yes | Custom field merge tag | | `content[].maxLength` | integer (int32) | Yes | Custom field max length | | `content[].type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `content[].createdDate` | string (date-time) | Yes | Create date | | `content[].lastModifiedDate` | string (date-time) | Yes | Last modified date | | `nextPageToken` | string | No | Pagination token to retrieve the next page | | `prevPageToken` | string | No | Pagination token to retrieve the previous page | | `totalElements` | integer (int64) | Yes | Total number of elements | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/api/v1/contacts/custom-fields?pageSize=1" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/custom-fields?pageSize=1", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) - [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) - [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) - [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/index.md # Contacts The API provides access to two main resources: * **Contacts**: Data associated with the individuals you need to contact. * **Lists**: Groups of contacts created for specific purposes. * **Custom Fields**: Additional fields that can be tailored to complement the basic contact fields. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint ### Contacts | Goal | Endpoint | |------|----------| | Browse or filter contacts | [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) | | Create a contact | [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) | | Retrieve one contact | [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) | | Change contact details | [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) | | Delete a contact | [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) | ### Lists | Goal | Endpoint | |------|----------| | Browse or filter contact lists | [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) | | Create a contact list | [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) | | Retrieve one contact list | [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) | | Rename or change a contact list | [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) | | Delete a contact list | [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) | | Add or remove contacts in bulk | [Add or remove multiple contacts to/from a list](https://developers.app.sinch.com/docs/api/contacts/modify-contacts-in-contact-list.md) | | Add one contact to a list | [Add contact to a list](https://developers.app.sinch.com/docs/api/contacts/add-contact-to-contact-list.md) | | Remove one contact from a list | [Remove contact from the contact list](https://developers.app.sinch.com/docs/api/contacts/remove-contact-from-contact-list.md) | ### Custom Fields | Goal | Endpoint | |------|----------| | Browse or filter custom fields | [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) | | Create a custom field | [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) | | Retrieve one custom field | [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) | | Change a custom field | [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) | | Delete a custom field | [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) | ## Endpoints ### Contacts | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) | `GET` | `/api/v1/contacts/contacts` | Retrieves a paginated list of contacts. | | [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) | `POST` | `/api/v1/contacts/contacts` | Creates a new contact in the account. | | [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) | `GET` | `/api/v1/contacts/contacts/{contactId}` | Retrieves details for a single contact by ID. | | [Update a contact](https://developers.app.sinch.com/docs/api/contacts/update-contact.md) | `PATCH` | `/api/v1/contacts/contacts/{contactId}` | Updates an existing contact. | | [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) | `DELETE` | `/api/v1/contacts/contacts/{contactId}` | Deletes a contact from the account. | ### Lists | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) | `GET` | `/api/v1/contacts/lists` | Retrieves a paginated list of contact lists. | | [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) | `POST` | `/api/v1/contacts/lists` | Creates a new contact list. | | [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) | `GET` | `/api/v1/contacts/lists/{listId}` | Retrieves details for a single contact list by ID. | | [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) | `PATCH` | `/api/v1/contacts/lists/{listId}` | Updates an existing contact list. | | [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) | `DELETE` | `/api/v1/contacts/lists/{listId}` | Deletes a contact list. | | [Add or remove multiple contacts to/from a list](https://developers.app.sinch.com/docs/api/contacts/modify-contacts-in-contact-list.md) | `PATCH` | `/api/v1/contacts/lists/{listId}/contacts` | Adds or removes multiple contacts to or from a contact list. | | [Add contact to a list](https://developers.app.sinch.com/docs/api/contacts/add-contact-to-contact-list.md) | `POST` | `/api/v1/contacts/lists/{listId}/contacts/{contactId}` | Adds a contact to a contact list. | | [Remove contact from the contact list](https://developers.app.sinch.com/docs/api/contacts/remove-contact-from-contact-list.md) | `DELETE` | `/api/v1/contacts/lists/{listId}/contacts/{contactId}` | Removes a contact from a contact list. | ### Custom Fields | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) | `GET` | `/api/v1/contacts/custom-fields` | Retrieves a paginated list of custom fields. | | [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) | `POST` | `/api/v1/contacts/custom-fields` | Creates a new custom field for contacts. | | [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) | `GET` | `/api/v1/contacts/custom-fields/{customFieldId}` | Retrieves details for a single custom field by ID. | | [Update a custom field](https://developers.app.sinch.com/docs/api/contacts/update-custom-field.md) | `PATCH` | `/api/v1/contacts/custom-fields/{customFieldId}` | Updates an existing custom field. | | [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) | `DELETE` | `/api/v1/contacts/custom-fields/{customFieldId}` | Deletes a custom field. | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/contacts/modify-contacts-in-contact-list.md # Add or remove multiple contacts to/from a list Adds or removes multiple contacts to or from a contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}/contacts` | | **Operation ID** | `modifyContactsInContactList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Contacts added/removed to/from list | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `contactsToAddIds` | array of string (uuid); min items: 0; max items: 1000 | No | | | `contactsToAddIds[]` | string (uuid) | No | List of contacts to add to the list in UUID format | | `contactsToRemoveIds` | array of string (uuid); min items: 0; max items: 1000 | No | | | `contactsToRemoveIds[]` | string (uuid) | No | List of contacts to remove from the list in UUID format | ### Example request body ```json { "contactsToAddIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ], "contactsToRemoveIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Contacts added/removed to/from list | `ListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | List id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `name` | string | Yes | List name | | `alias` | string | Yes | List alias | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "contactsToAddIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ], "contactsToRemoveIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "contactsToAddIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ], "contactsToRemoveIds": [ "025e93d3-051b-43f9-b12e-4b5842228dee" ] }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/remove-contact-from-contact-list.md # Remove contact from the contact list Removes a contact from a contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}/contacts/{contactId}` | | **Operation ID** | `removeContactFromContactList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — No Content | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | | `contactId` | string (uuid) | Yes | Contact id to add in UUID format | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | No Content | — | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts/4a03d2d8-1f85-463f-bdb4-2891c17258a7" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee/contacts/4a03d2d8-1f85-463f-bdb4-2891c17258a7", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Update a contact list](https://developers.app.sinch.com/docs/api/contacts/update-contact-list.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/update-contact-list.md # Update a contact list Updates an existing contact list. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/lists/{listId}` | | **Operation ID** | `updateContactList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — List is updated | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `listId` | string (uuid) | Yes | Contact list id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | Yes | Contact list name | | `alias` | string | No | Contact list alias | ### Example request body ```json { "name": "My list", "alias": "List1" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | List is updated | `ListData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | List id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `name` | string | Yes | List name | | `alias` | string | Yes | List alias | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name": "My list", "alias": "List1" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/lists/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "My list", "alias": "List1" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contact lists page](https://developers.app.sinch.com/docs/api/contacts/get-contact-lists-page.md) - [Create a contact list](https://developers.app.sinch.com/docs/api/contacts/create-contact-list.md) - [Get a single contact list](https://developers.app.sinch.com/docs/api/contacts/get-contact-list-by-id.md) - [Delete a contact list](https://developers.app.sinch.com/docs/api/contacts/delete-contact-list-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/update-contact.md # Update a contact Updates an existing contact. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/contacts/{contactId}` | | **Operation ID** | `updateContact` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Contact is updated | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `contactId` | string (uuid) | Yes | Contact id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `firstName` | string | No | Contact first name | | `lastName` | string | No | Contact last name | | `alias` | string | No | Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms | | `dateOfBirth` | string (date) | No | Date of birth | | `country` | string | No | Country | | `state` | string | No | State | | `location` | string | No | Location | | `note` | string | No | Note | | `channels` | array of object | No | Contact channels | | `channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `channels[].type` | string; enum: `SMS`, `WHATSAPP` | Yes | Contact channel type | | `channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `lists` | array of object | No | Contact lists | | `lists[].id` | string (uuid) | Yes | List id in UUID format | | `customFields` | array of object | No | Contact custom fields | | `customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `customFields[].value` | string | Yes | Custom field value | ### Example request body ```json { "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Contact is updated | `ContactData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Contact id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `firstName` | string | Yes | Contact first name | | `lastName` | string | Yes | Contact last name | | `fullName` | string | Yes | Contact full name | | `alias` | string | Yes | Contact alias | | `dateOfBirth` | string (date) | No | Date of birth | | `country` | string | Yes | Country | | `state` | string | Yes | State | | `location` | string | Yes | Location | | `note` | string | Yes | Note | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | | `customFields` | array of object | Yes | List of custom fields | | `customFields[].id` | string (uuid) | Yes | Custom Field id in UUID format | | `customFields[].mergeTag` | string | Yes | Custom field merge tag | | `customFields[].value` | string | Yes | Custom field value | | `customFields[].type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `channels` | array of object | Yes | Contact channels | | `channels[].channelId` | string | Yes | Contact channel id (in case phone number - in E164 international format) | | `channels[].type` | string; enum: `SMS`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | Yes | Contact channel type | | `channels[].subscriptionState` | string; enum: `SUBSCRIBED`, `UNSUBSCRIBED` | No | Subscription state | | `lists` | array of object | Yes | Contact lists | | `lists[].id` | string (uuid) | Yes | List id in UUID format | | `lists[].name` | string | Yes | List name | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "firstName": "Adam", "lastName": "Smith", "alias": "user1234", "dateOfBirth": "2022-08-18", "country": "US", "state": "CA", "location": "Sunset Blvd", "note": "Note", "channels": [ { "channelId": "+15553456783", "type": "SMS", "subscriptionState": "UNSUBSCRIBED" } ], "lists": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee" } ], "customFields": [ { "id": "025e93d3-051b-43f9-b12e-4b5842228dee", "value": "John" } ] }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get contacts page](https://developers.app.sinch.com/docs/api/contacts/get-contacts-page.md) - [Create a contact](https://developers.app.sinch.com/docs/api/contacts/create-contact.md) - [Get a single contact](https://developers.app.sinch.com/docs/api/contacts/get-contact-by-id.md) - [Delete a contact](https://developers.app.sinch.com/docs/api/contacts/delete-contact-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/contacts/update-custom-field.md # Update a custom field Updates an existing custom field. | | | |---|---| | **Service** | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/{customFieldId}` | | **Operation ID** | `updateCustomField` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Custom field is updated | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customFieldId` | string (uuid) | Yes | Custom field id in UUID format | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `label` | string | No | Custom field label | | `maxLength` | integer (int32) | No | Custom field max length | ### Example request body ```json { "label": "Contact name", "maxLength": 30 } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Custom field is updated | `CustomFieldData` | | 400 | Request has incorrect values | `InvalidInputApiError` | | 401 | No valid authentication details were provided | — | | 403 | The authenticated user or account doesn't have permission | — | | 404 | The specified resource not found | `ApiError` | | 409 | Conflict. The entity already exists. | `ApiError` | | 500 | Internal server error | `ApiError` | | 501 | Request not recognised | — | | 502 | Invalid server response | — | | 503 | Server currently unavailable | — | | 504 | Gateway time out | — | ### 200 response schema - **Content-Type:** `*/*` | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | Yes | Custom field id in UUID format | | `accountId` | string | Yes | Account id | | `vendorId` | string | Yes | Vendor id | | `label` | string | Yes | Custom field label | | `mergeTag` | string | Yes | Custom field merge tag | | `maxLength` | integer (int32) | Yes | Custom field max length | | `type` | string; enum: `DATE`, `NUMBER`, `PHONE`, `TEXT`, `URL`, `ZIP_CODE`, `NAME`, `EMAIL` | Yes | Custom field type | | `createdDate` | string (date-time) | Yes | Create date | | `lastModifiedDate` | string (date-time) | Yes | Last modified date | ### 400 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | | `invalidFields` | array of object | Yes | List of invalid fields | | `invalidFields[].name` | string | Yes | Invalid input field name | | `invalidFields[].channelType` | string; enum: `PHONE`, `WHATSAPP`, `GBM`, `INSTAGRAM`, `FACEBOOK`, `EMAIL` | No | Invalid channel type | | `invalidFields[].code` | string; enum: `must_not_be_empty`, `must_be_empty`, `must_not_be_null`, `invalid_length`, `duplicated_value`, `invalid_format`, `type_mismatch`, `missing_parameter`, `invalid_reference`, `incorrect_operation`, `no_such_pattern`, `constraint_violation` | Yes | Invalid input value code | | `invalidFields[].reason` | string | Yes | Error message | | `invalidFields[].invalidIds` | array of string | No | | ### 404 and 409 and 500 response schema - **Content-Type:** `application/json` | Property | Type | Required | Description | |----------|------|----------|-------------| | `uuid` | string (uuid) | Yes | Error id in UUID format | | `type` | string; enum: `validation`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `message_not_readable`, `internal_server_error`, `request_not_recognised`, `forbidden`, `bad_gateway`, `payment_required`, `unauthorized`, `unknown` | Yes | Error type | | `title` | string | Yes | Error title | | `detail` | string | Yes | Error additional details | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Contact name", "maxLength": 30 }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/api/v1/contacts/custom-fields/025e93d3-051b-43f9-b12e-4b5842228dee", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ "label": "Contact name", "maxLength": 30 }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Request has incorrect values - **401 Unauthorized**: No valid authentication details were provided - **403 Forbidden**: The authenticated user or account doesn't have permission - **404 Not Found**: The specified resource not found - **409 Conflict**: Conflict. The entity already exists. - **500 Internal Server Error**: Internal server error - **501 Not Implemented**: Request not recognised - **502 Bad Gateway**: Invalid server response - **503 Service Unavailable**: Server currently unavailable - **504 Gateway Timeout**: Gateway time out ## Related endpoints - [Get custom fields page](https://developers.app.sinch.com/docs/api/contacts/get-custom-fields-page.md) - [Create a custom field](https://developers.app.sinch.com/docs/api/contacts/create-custom-field.md) - [Get a single custom field](https://developers.app.sinch.com/docs/api/contacts/get-custom-field-by-id.md) - [Delete a custom field](https://developers.app.sinch.com/docs/api/contacts/delete-custom-field-by-id.md) [← Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) --- ### Source: docs/api/dedicated-numbers/create-assignment.md # Create assignment Assign an available dedicated number to the authenticated account and attach a required label and metadata. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/{numberId}/assignment` | | **Operation ID** | `CreateAssignment` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Created | | **Required body** | `label` and `metadata` | ### Minimal request ```json { "label": "ExampleLabel", "metadata": {} } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `numberId` | string | Yes | unique identifier | ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body - **Description:** Request body. - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `label` | string | Yes | | | `metadata` | object (string values) | Yes | | The request schema requires both properties, even though the operation description says to specify a label or metadata. ### Example request body ```json { "label": "ExampleLabel", "metadata": { "Key1": "value1", "Key2": "value2" } } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Created | `Assignment` | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `404response` | ### 201 response schema (`Assignment`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | No | | | `metadata` | object (string values) | No | | | `number_id` | string | No | | | `label` | string | No | | ### Example 201 response ```json { "label": "cillum irure", "number_id": "et pariatur" } ``` ### 403 and 404 response schemas | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985/assignment" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" \ -H "Content-Type: application/json" \ -d '{ "label": "ExampleLabel", "metadata": { "Key1": "value1", "Key2": "value2" } }' ``` ### JavaScript (fetch) ```javascript const numberId = "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985"; const response = await fetch( `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/${numberId}/assignment`, { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8", "Content-Type": "application/json" }, body: JSON.stringify({ label: "ExampleLabel", metadata: {Key1: "value1", Key2: "value2"} }) } ); const result = await response.json(); console.log(result); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No number matches the supplied `numberId`. - The operation description also documents a conflict when the selected number is unavailable, although `409` is not declared in this operation's `responses` map. ## Related endpoints - [Get numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-numbers.md) - [Get number by ID](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-number-by-id.md) - [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) ## Specification details Assign the specified number to the authenticated account. Use the body of the request to specify a label or metadata for this number assignment. If you receive a *conflict* error then the number that you have selected is unavailable for assignment. This means that the number is either already assigned to another account, or has an available_after date in the future. Should this occur, perform another search and select a different number. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/delete-assignment.md # Delete assignment Release a dedicated number from the authenticated account. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/{numberId}/assignment` | | **Operation ID** | `DeleteAssignment` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — No Content | | **Required** | `numberId` path parameter and `Accept` header | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `numberId` | string | Yes | unique identifier | ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | No Content | string (binary) | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | ### 204 response schema - **Content-Type:** `application/json;charset=UTF-8` - **Type:** string - **Format:** binary - **Description:** No Content ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985/assignment" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" ``` ### JavaScript (fetch) ```javascript const numberId = "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985"; const response = await fetch( `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/${numberId}/assignment`, { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8" } } ); console.log(response.status); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) - [Create assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/create-assignment.md) - [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) ## Specification details Release the dedicated number from your account. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/get-assigned-numbers.md # Get assigned numbers List dedicated numbers assigned to the authenticated account, with inventory details and assignment metadata. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/assignments` | | **Operation ID** | `GetAssignedNumbers` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | `Accept` header | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page_size` | integer (int32) | No | Number of results returned per page, default 50 | | `token` | string | No | In paginated data the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. | | `number_id` | string | No | Unique identifier of a specific number | | `matching` | string | No | Filters results by a pattern of digits contained within the number | | `country` | string | No | Filter results by ISO_3166 country code, 2 character code to filter available numbers by country | | `type` | string | No | Filter results by Number type. When both `type` and `types` are provided, `types` will take precedence, and `type` will be ignored. Enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `types` | array of strings | No | Filter results by Number Types Items enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `classification` | string | No | Filter results by Number Classification Enum: `BRONZE`, `SILVER`, `GOLD` | | `service_types` | string | No | Filter results by capabilities Enum: `SMS`, `TTS`, `MMS` | | `label` | string | No | Filter results by a matching label | | `sort_by` | string | No | Sort results by property Enum: `ACCOUNT`, `ACTION`, `DESTINATION_ADDRESS`, `DESTINATION_ADDRESS_COUNTRY`, `FORMAT`, `SOURCE_ADDRESS`, `SOURCE_ADDRESS_COUNTRY`, `TIMESTAMP` | | `sort_direction` | string | No | Sort direction Enum: `ASCENDING`, `DESCENDING` | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `AssignedNumberListResponse` | | 401 | Unauthorized | `403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `data` | array | No | List of result items. | | `pagination` | object (`TokenPagination`) | No | Cursor-style pagination used by Dedicated Numbers list endpoints. Pass `next_token` back as the `token` query parameter to fetch the next page. | #### `data` item schema (`AssignedNumber`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `assignment` | object (`Assignment`) | No | | | `number` | object (`DedicatedNumber`) | No | | ##### `assignment` schema (`Assignment`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | No | | | `metadata` | object (string values) | No | | | `number_id` | string | No | | | `label` | string | No | | ##### `number` schema (`DedicatedNumber`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | No | Unique identifier of the dedicated number | | `phone_number` | string | No | Phone number as a string (digits; may include a leading +) | | `country` | string | No | ISO 3166-1 alpha-2 country code | | `type` | string | No | Dedicated number type Enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `classification` | string | No | Enum: `BRONZE`, `SILVER`, `GOLD` | | `available_after` | string (date-time) | No | Earliest time this number can be assigned | | `capabilities` | array of strings | No | Capabilities supported by this number Items enum: `SMS`, `TTS`, `MMS` | #### `pagination` schema (`TokenPagination`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `page_size` | integer (int32) | No | Number of results returned in this page | | `next_token` | string (uuid) | No | Token for the next page of results. Omit or null when there are no further pages. Pass this value as the `token` query parameter on the next request. | ### Example 200 response ```json { "pagination": { "next_token": "0428d673-0f75-4063-9493-e89d75f13438", "page_size": 5 }, "data": [ { "assignment": { "metadata": { "Key1": "value1", "Key2": "value2" }, "label": "LabelTest0", "id": "be3cb602-7c00-4c87-ae4b-b8defc04f179", "number_id": "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985" }, "number": { "id": "03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3", "phone_number": "61436489205", "country": "AU", "type": "MOBILE", "classification": "BRONZE", "available_after": "2019-08-06T23:56:15.633Z", "capabilities": ["SMS"] } } ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/assignments?country=AU&types=MOBILE%2CLANDLINE&page_size=20&sort_direction=ASCENDING" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" ``` ### JavaScript (fetch) ```javascript const url = new URL("https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/assignments"); url.searchParams.set("country", "AU"); url.searchParams.set("types", "MOBILE,LANDLINE"); url.searchParams.set("page_size", "20"); url.searchParams.set("sort_direction", "ASCENDING"); const response = await fetch(url, { headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8" } }); const result = await response.json(); console.log(result.data, result.pagination?.next_token); ``` ## Error handling - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. ## Related endpoints - [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) - [Update assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/update-assignment.md) - [Delete assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/delete-assignment.md) ## Specification details Retrieves the list of assigned dedicated numbers. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/get-assignment.md # Get assignment Retrieve the assignment record, including its label and metadata, for a dedicated number. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/{numberId}/assignment` | | **Operation ID** | `GetAssignment` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | `numberId` path parameter and `Accept` header | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `numberId` | string | Yes | unique identifier | ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `Assignment` | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `404response` | ### 200 response schema (`Assignment`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | No | | | `metadata` | object (string values) | No | | | `number_id` | string | No | | | `label` | string | No | | ### Example 200 response ```json { "metadata": { "key1": "value1" }, "label": "LabelTest0", "id": "be3cb602-7c00-4c87-ae4b-b8defc04f179", "number_id": "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985" } ``` ### 403 and 404 response schemas | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985/assignment" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" ``` ### JavaScript (fetch) ```javascript const numberId = "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985"; const response = await fetch( `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/${numberId}/assignment`, { headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8" } } ); const result = await response.json(); console.log(result); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No assignment matches the supplied `numberId`. ## Related endpoints - [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) - [Update assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/update-assignment.md) - [Delete assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/delete-assignment.md) ## Specification details Use this endpoint to view details of the assignment including the label and metadata. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/get-number-by-id.md # Get number by ID Retrieve the details and capabilities of one dedicated number before assigning it. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/{id}` | | **Operation ID** | `GetNumberById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | `id` path parameter and `Accept` header | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | Yes | unique identifier | ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `DedicatedNumber` | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `404response` | ### 200 response schema (`DedicatedNumber`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | No | Unique identifier of the dedicated number | | `phone_number` | string | No | Phone number as a string (digits; may include a leading +) | | `country` | string | No | ISO 3166-1 alpha-2 country code | | `type` | string | No | Dedicated number type Enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `classification` | string | No | Enum: `BRONZE`, `SILVER`, `GOLD` | | `available_after` | string (date-time) | No | Earliest time this number can be assigned | | `capabilities` | array of strings | No | Capabilities supported by this number Items enum: `SMS`, `TTS`, `MMS` | ### Example 200 response ```json { "id": "be3cb602-7c00-4c87-ae4b-b8defc04f179", "phone_number": "614111111111", "country": "AU", "type": "MOBILE", "classification": "SILVER", "available_after": "2019-06-21T04:04:31.707Z", "capabilities": ["SMS", "MMS"] } ``` ### 403 and 404 response schemas | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/7ca628a8-08b0-4e42-aeb8-960b37049c31" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" ``` ### JavaScript (fetch) ```javascript const numberId = "7ca628a8-08b0-4e42-aeb8-960b37049c31"; const response = await fetch( `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/${numberId}`, { headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8" } } ); const result = await response.json(); console.log(result); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No number matches the supplied `id`. ## Related endpoints - [Get numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-numbers.md) - [Create assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/create-assignment.md) ## Specification details Get details about a specific dedicated number. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/get-numbers.md # Get numbers Search the available dedicated-number inventory using country, digit pattern, capability, number type, and pagination filters. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated` | | **Operation ID** | `GetNumbers` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | None | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `country` | string | No | ISO_3166 country code, 2 character code to filter available numbers by country | | `matching` | string | No | Filters results by a pattern of digits contained within the number | | `page_size` | integer (int32) | No | number of results returned per page, default 50 | | `service_types` | string | No | filter results to include numbers with certain capabilities Enum: `SMS`, `TTS`, `MMS` | | `types` | array of strings | No | Filter results by one or more number types. Pass repeated query parameters or a comma-separated list (for example `types=MOBILE,LANDLINE,TOLL_FREE`). Items enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `token` | string (uuid) | No | In paginated data the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `NumbersListResponse` | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `data` | array | No | List of result items. | | `pagination` | object (`TokenPagination`) | No | Cursor-style pagination used by Dedicated Numbers list endpoints. Pass `next_token` back as the `token` query parameter to fetch the next page. | #### `data` item schema (`DedicatedNumber`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string (uuid) | No | Unique identifier of the dedicated number | | `phone_number` | string | No | Phone number as a string (digits; may include a leading +) | | `country` | string | No | ISO 3166-1 alpha-2 country code | | `type` | string | No | Dedicated number type Enum: `MOBILE`, `LANDLINE`, `TEN_DLC`, `TOLL_FREE`, `SHORT_CODE`, `HOSTED_TEN_DLC`, `HOSTED_TOLL_FREE` | | `classification` | string | No | Enum: `BRONZE`, `SILVER`, `GOLD` | | `available_after` | string (date-time) | No | Earliest time this number can be assigned | | `capabilities` | array of strings | No | Capabilities supported by this number Items enum: `SMS`, `TTS`, `MMS` | #### `pagination` schema (`TokenPagination`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `page_size` | integer (int32) | No | Number of results returned in this page | | `next_token` | string (uuid) | No | Token for the next page of results. Omit or null when there are no further pages. Pass this value as the `token` query parameter on the next request. | ### Example 200 response ```json { "pagination": { "next_token": "0428d673-0f75-4063-9493-e89d75f13438", "page_size": 5 }, "data": [ { "id": "03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3", "phone_number": "61436489205", "country": "AU", "type": "MOBILE", "classification": "BRONZE", "available_after": "2019-08-06T23:56:15.633Z", "capabilities": ["SMS"] } ] } ``` ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated?country=AU&types=MOBILE%2CLANDLINE&page_size=20" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const url = new URL("https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated"); url.searchParams.set("country", "AU"); url.searchParams.set("types", "MOBILE,LANDLINE"); url.searchParams.set("page_size", "20"); const response = await fetch(url, { headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result.data, result.pagination?.next_token); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Get number by ID](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-number-by-id.md) - [Create assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/create-assignment.md) - [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) ## Specification details Get a list of available dedicated numbers, filtered by requirements. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/dedicated-numbers/index.md # Dedicated Numbers Find, assign, inspect, update, and release dedicated numbers for your Sinch account. This paid feature must be enabled on your account. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Search the available number inventory | [Get numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-numbers.md) | | Inspect one number before assigning it | [Get number by ID](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-number-by-id.md) | | List numbers already assigned to your account | [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) | | View an assignment's label and metadata | [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) | | Assign an available number to your account | [Create assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/create-assignment.md) | | Change an assignment's label or metadata | [Update assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/update-assignment.md) | | Release a number from your account | [Delete assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/delete-assignment.md) | Typical lifecycle: search → inspect → assign → manage → release. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Get numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-numbers.md) | `GET` | `/v1/messaging/numbers/dedicated` | Get numbers | | [Get number by ID](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-number-by-id.md) | `GET` | `/v1/messaging/numbers/dedicated/{id}` | Get number by ID | | [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) | `GET` | `/v1/messaging/numbers/dedicated/{numberId}/assignment` | Get assignment | | [Create assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/create-assignment.md) | `POST` | `/v1/messaging/numbers/dedicated/{numberId}/assignment` | Create assignment | | [Delete assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/delete-assignment.md) | `DELETE` | `/v1/messaging/numbers/dedicated/{numberId}/assignment` | Delete assignment | | [Update assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/update-assignment.md) | `PATCH` | `/v1/messaging/numbers/dedicated/{numberId}/assignment` | Update assignment | | [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) | `GET` | `/v1/messaging/numbers/dedicated/assignments` | Get assigned numbers | ## Specification details The Numbers API allows your to purchase, provision and configure the dedicated numbers assigned to your Sinch account. To learn more about the benefits of dedicated numbers, and their use cases, visit our [feature page](https://support.app.sinch.com/hc/en-us/articles/10526389880207-Dedicated-numbers). This is a paid feature and must be enabled on your account. Please contact [support@app.sinch.com](mailto:support@app.sinch.com) or your account manager. ## Concepts This API allows you to purchase and assign to your account a number from a pool of dedicated numbers. Dedicated numbers are priced differently according to their classification. The following is the system by which we classify dedicated numbers. | Pattern Type | Gold| Silver | |---|---|---| | Same Number | Six of same (e.g. 999999) | Five of same (e.g. 999991 or 199999) | | Sequence | Six in sequence (e.g. 234567, or 765432) | Five in sequence (e.g. 245678, 456782, or 287654) | | Triplets | Two identical (e.g. 123123) or two double (e.g. 444666) | Identical pairs within triplets (e.g. 004008, or 400800), one identical and one in sequence (e.g. 444789, or 345777), or mirror image (e.g. 468864)| |Pair|Three identical (e.g. 454545)|Three non-identical (e.g. 447700) or three in sequence (e.g. 232425, or 090807)| Any numbers that do not meet the criteria for Gold or Silver are classified as Bronze. For pricing on dedicated numbers please refer to the Numbers page in our Hub web portal, or speak with your Sinch Account Manager. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/dedicated-numbers/update-assignment.md # Update assignment Keep a dedicated-number assignment while replacing its label and metadata values. | | | |---|---| | **Service** | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/{numberId}/assignment` | | **Operation ID** | `UpdateAssignment` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — OK | | **Required body** | `label` and `metadata` | ### Minimal request ```json { "label": "ExampleLabel", "metadata": {} } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `numberId` | string | Yes | unique identifier | ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body - **Description:** Request body. - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `label` | string | Yes | | | `metadata` | object (string values) | Yes | | The request schema requires both properties, although the operation description says data that should not be updated can be excluded. ### Example request body ```json { "label": "ExampleLabel", "metadata": { "Key1": "value1", "Key2": "value2" } } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | OK | `Assignment` | | 401 | No valid authentication details were provided | None | | 403 | Unexpected error in API call. See HTTP response body for details. | `403response` | ### 204 response schema (`Assignment`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | No | | | `metadata` | object (string values) | No | | | `number_id` | string | No | | | `label` | string | No | | ### Example 204 response ```json { "id": "b06387c0-f4d9-4333-8657-c819bede79c3", "number_id": "073fb6bd-f054-4644-aada-8fb204145d77" } ``` ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985/assignment" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json;charset=UTF-8" \ -H "Content-Type: application/json" \ -d '{ "label": "ExampleLabel", "metadata": { "Key1": "value1", "Key2": "value2" } }' ``` ### JavaScript (fetch) ```javascript const numberId = "b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985"; const response = await fetch( `https://eu.app.api.sinch.com/v1/messaging/numbers/dedicated/${numberId}/assignment`, { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json;charset=UTF-8", "Content-Type": "application/json" }, body: JSON.stringify({ label: "ExampleLabel", metadata: {Key1: "value1", Key2: "value2"} }) } ); console.log(response.status); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Get assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assignment.md) - [Delete assignment](https://developers.app.sinch.com/docs/api/dedicated-numbers/delete-assignment.md) - [Get assigned numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/get-assigned-numbers.md) ## Specification details Retain the dedicated number assignment, and edit or add additional metadata or title information. You can exclude any data from the body of this request that you do not want updated. [← Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) --- ### Source: docs/api/delivery-reports/check-delivery-reports.md # Check delivery reports Return unconfirmed delivery reports for the account (newest status changes not yet confirmed). Max 100 per response. Same reports repeat until confirmed. Prefer [Webhooks](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) over polling when possible. Retention: 45 days. | | | |---|---| | **Service** | [Delivery Reports](https://developers.app.sinch.com/docs/api/delivery-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/delivery_reports` | | **Operation ID** | `CheckDeliveryReports` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Unconfirmed reports | | **Required** | None (no path, query, or body parameters) | ### Poll pattern 1. Call this endpoint. 2. Process each `delivery_reports[]` item. 3. Confirm IDs with [Confirm delivery reports as received](https://developers.app.sinch.com/docs/api/delivery-reports/confirm-delivery-reports-as-received.md). ### Example success body ```json { "delivery_reports": [ { "callback_url": "https://my.callback.url.com", "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043", "source_number": "+61491570157", "date_received": "2017-05-20T06:30:37.642Z", "status": "enroute", "delay": 0, "billing_units": 1, "submitted_date": "2017-05-20T06:30:37.639Z", "original_text": "My first message!", "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "metadata": { "key1": "value1", "key2": "value2" } } ] } ``` Note: In a delivery report, `source_number` is the destination of the original outbound message (addresses are inverted relative to send). ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Unconfirmed reports | `Checkdeliveryreportsresponse` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `delivery_reports` | array | No | The oldest 100 unconfirmed delivery reports. Min items: 0. Max items: 100. | #### `delivery_reports` item schema (`DeliveryReport`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `callback_url` | string | No | The URL specified as the callback URL in the original submit message request | | `date_received` | string (date-time) | No | The date and time at which this delivery report was generated in UTC. | | `delay` | integer (int32) | No | Deprecated, no longer in use. Deprecated. | | `billing_units` | integer (int32) | No | The billing units of this report | | `delivery_report_id` | string (uuid) | No | Unique ID for this delivery report | | `message_id` | string (uuid) | No | Unique ID of the original message | | `metadata` | object | No | Any metadata that was included in the original submit message request | | `original_text` | string | No | Text of the original message. | | `source_number` | string | No | Address from which this delivery report was received. Min length: 1. Max length: 15. | | `status` | string | No | The status of the message. Enum: `undefined`, `queued`, `processing`, `processed`, `failed`, `scheduled`, `cancelled`, `delivered`, `expired`, `enroute`, `held`, `submitted`, `rejected`, `read` | | `submitted_date` | string (date-time) | No | The date and time when the message status changed in UTC. For a delivered DR this may indicate the time at which the message was received on the handset. | | `vendor_account_id` | object | No | | ##### `vendor_account_id` schema (`VendorAccountId`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `vendor_id` | string | No | | | `account_id` | string | No | The account used to submit the original message. | Notes for implementers: - Callback push payloads in the service overview may include `error_code`; that field is **not** declared on the `DeliveryReport` schema returned by this polling endpoint. - Status meanings and error codes for push notifications are documented under [Delivery Reports → Specification details](https://developers.app.sinch.com/docs/api/delivery-reports/index.md#specification-details). ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/delivery_reports" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/delivery_reports", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result.delivery_reports); ``` ## Error handling - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. ## Related endpoints - [Confirm delivery reports as received](https://developers.app.sinch.com/docs/api/delivery-reports/confirm-delivery-reports-as-received.md) - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) ## Specification details Check for any delivery reports that have been received. Delivery reports are a notification of the change in status of a message as it is being processed. Each request to the check delivery reports endpoint will return any delivery reports received that have not yet been confirmed using the confirm delivery reports endpoint. A response from the check delivery reports endpoint will have the following structure: ```json { "delivery_reports": [ { "callback_url": "https://my.callback.url.com", "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043", "source_number": "+61491570157", "date_received": "2017-05-20T06:30:37.642Z", "status": "enroute", "delay": 0, "billing_units": 1, "submitted_date": "2017-05-20T06:30:37.639Z", "original_text": "My first message!", "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "metadata": { "key1": "value1", "key2": "value2" } }, { "callback_url": "https://my.callback.url.com", "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b", "source_number": "+61491570158", "date_received": "2017-05-21T01:46:42.579Z", "status": "enroute", "delay": 0, "billing_units": 1, "submitted_date": "2017-05-21T01:46:42.574Z", "original_text": "My second message!", "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "metadata": { "key1": "value1", "key2": "value2" } } ] } ``` Each delivery report will contain details about the message, including any metadata specified and the new status of the message (as each delivery report indicates a change in status of a message) and the timestamp at which the status changed. Every delivery report will have a unique delivery report ID for use with the confirm delivery reports endpoint. *Note: The source number and destination number properties in a delivery report are the inverse of those specified in the message that the delivery report relates to. The source number of the delivery report is the destination number of the original message.* Subsequent requests to the check delivery reports endpoint will return the same delivery reports and a maximum of 100 delivery reports will be returned in each request. Applications should use the confirm delivery reports endpoint in the following pattern so that delivery reports that have been processed are no longer returned in subsequent check delivery reports requests. The expiry date for getting an entity is 45 days. 1. Call check delivery reports endpoint 2. Process each delivery report 3. Confirm all processed delivery reports using the confirm delivery reports endpoint *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check delivery reports endpoint.* [← Delivery Reports](https://developers.app.sinch.com/docs/api/delivery-reports/index.md) --- ### Source: docs/api/delivery-reports/confirm-delivery-reports-as-received.md # Confirm delivery reports as received Mark delivery reports as confirmed so they are no longer returned by [Check delivery reports](https://developers.app.sinch.com/docs/api/delivery-reports/check-delivery-reports.md). Up to 100 IDs per request. Retention: 45 days. | | | |---|---| | **Service** | [Delivery Reports](https://developers.app.sinch.com/docs/api/delivery-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/delivery_reports/confirmed` | | **Operation ID** | `ConfirmDeliveryReportsAsReceived` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `202` — Requested delivery reports will be marked as confirmed | | **Required body** | `delivery_report_ids` (array of UUIDs, max 100) | ### Minimal request ```json { "delivery_report_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d" ] } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `delivery_report_ids` | array of string (uuid) | Yes | Array of unique IDs for the delivery report that this notification represents. Max items: 100. | ### Example request body ```json { "delivery_report_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | Requested delivery reports will be marked as confirmed | object (`text/plain`) | | 400 | Bad request | `400response` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 202 response schema - **Content-Type:** `text/plain` - **Schema:** `type: object` - **Description:** Requested delivery reports will be marked as confirmed No properties are declared on this response schema. ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/delivery_reports/confirmed" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "delivery_report_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/delivery_reports/confirmed", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ delivery_report_ids: [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] }) }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Bad request. Returned when the request body is invalid. - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. ## Related endpoints - [Check delivery reports](https://developers.app.sinch.com/docs/api/delivery-reports/check-delivery-reports.md) ## Specification details Mark a delivery report as confirmed so it is no longer return in check delivery reports requests. The confirm delivery reports endpoint is intended to be used in conjunction with the check delivery reports endpoint to allow for robust processing of delivery reports. Once one or more delivery reports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they are no longer returned in subsequent check delivery reports requests. The confirm delivery reports endpoint takes a list of delivery report IDs as follows: ```json { "delivery_report_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` The expiry date for getting an entity is 45 days. Up to 100 delivery reports can be confirmed in a single confirm delivery reports request. [← Delivery Reports](https://developers.app.sinch.com/docs/api/delivery-reports/index.md) --- ### Source: docs/api/delivery-reports/index.md # Delivery Reports If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request. An alternative to delivery reports via a callback URL is custom webhooks using the [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) API. Polling via the endpoints below is an alternative to push. Prefer webhooks when possible. Delivery reports may carry an additional charge; contact your Account Manager or Support (`support@app.sinch.com`). Entity retention is 45 days. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Fetch up to 100 unconfirmed delivery reports | [Check delivery reports](https://developers.app.sinch.com/docs/api/delivery-reports/check-delivery-reports.md) | | Mark processed report IDs so they stop returning (up to 100 per call) | [Confirm delivery reports as received](https://developers.app.sinch.com/docs/api/delivery-reports/confirm-delivery-reports-as-received.md) | Recommended poll pattern: check → process → confirm. Repeat until empty. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Check delivery reports](https://developers.app.sinch.com/docs/api/delivery-reports/check-delivery-reports.md) | `GET` | `/v1/delivery_reports` | Check delivery reports | | [Confirm delivery reports as received](https://developers.app.sinch.com/docs/api/delivery-reports/confirm-delivery-reports-as-received.md) | `POST` | `/v1/delivery_reports/confirmed` | Confirm delivery reports as received | ## Specification details If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request. An alternative to delivery reports via a callback URL is custom webhooks using the webhooks management API. All notifications are JSON encoded and the request expects to receive a response in the HTTP 200 range. If a valid response isn't received the request will be retried in an exponentially backing off fashion. Delivery Reports may carry an additional charge. For pricing, please contact your Account Manager or Support Team (). To include billing units in your delivery receipts via Webhooks, ensure that the switch "Enable billing units in Delivery Reports and Callbacks" is enabled in the API settings of your account. For delivery reports or changes in the status of a message, the POST request to the specified URL will be as follows: _Note, multiple delivery report notifications will be received for a single message._ ```json { "callback_url":"http://mockbin.org/bin/ac52ebd4-eca1-4c86-bf38-4dce79633906", "delivery_report_id":"693e87f2-a553-4281-9ffe-ddf04cbc4bf3", "source_number":"+61491570156", "date_received":"2016-11-03T11:49:02.807Z", "status":"delivered", "delay":0, "billing_units":1, "submitted_date":"2016-11-03T11:49:01.551Z", "original_text":"Hello world!", "message_id":"389dc1a8-62a4-4110-ba61-af94806c006f", "vendor_account_id":{ "vendor_id":"SinchEU", "account_id":"MyAccount" }, "error_code":"220", "metadata":{ "key":"value" } } ``` The properties included in the notification are as follows: * **Callback URL**: The URL specified as the callback URL in the original submit message request. * **Delivery Report ID**: A unique ID for the delivery report that this notification represents. * **Source Number**: The destination address of the original message. * **Date Received**: The date and time at which this notification was generated in UTC. * **Status**: The status of the message as indicated by this delivery report. The status field can be one of the following values: * `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed). * `submitted`: Message has been submitted to a provider/carrier for delivery. * `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible). * `expired`: The message has expired. * `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered * `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider. * **Delay**: _Deprecated, no longer in use_ * **Billing Units**: The number of billing units charged for the message. * **Submitted Date**: Date time status of the message changed in UTC. For a delivered DR this may indicate the time at which the message was received on the handset. * **Original Text**: Text of the original message. * **Message ID**: ID of the original message. * **Vendor Account ID**: The account used to submit the original message. The vendor will always be `SinchEU` * **Error Code**: A status code which provides additional information about the message status: * `101`: Message being processed by the gateway. * `102`: Message is being rerouted to a different provider after failing via the first provider. * `151`: Message held for screening. * `200`: Message submitted to downstream provider for delivery. * `210`: Message accepted by downstream provider. * `211`: Message is enroute for delivery by provider. * `212`: Message submitted. Delivery pending. * `213`: Message scheduled for delivery by downstream provider. * `220`: Message delivered. * `221`: Message delivered to the handset. * `320`: Message validity period has expired (prior to submission). * `401`: Message validity period has expired (before delivery). * `301`: Usage threshold reached. Message discarded. * `302`: Destination address blocked. Message discarded. * `303`: Source address blocked. Message discarded. * `304`: Message dropped. Contact support. * `305`: Message discarded due to duplicate detection. * `402`: Message rejected by downstream provider. * `403`: Message skipped by downstream provider. * `410`: Invalid source address. * `411`: Invalid destination address. * `412`: Destination address blocked. * `413`: SMS service unavailable on destination. * `414`: Destination unreachable. * `330`: Gateway failure. * `331`: Message discarded. * `332`: No available route to destination. * `333`: Source address unsupported for this destination. * `400`: Message failed; undeliverable. * `405`: Message cancelled or deleted by provider. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/index.md # API reference Sinch Engage API documentation generated from the OpenAPI specification. ## Messaging | Service | Description | |---------|-------------| | [Messages](https://developers.app.sinch.com/docs/api/messages/index.md) | The Sinch Messages API provides a number of endpoints for building powerful two-way messaging applications. | | [Delivery Reports](https://developers.app.sinch.com/docs/api/delivery-reports/index.md) | If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request. | | [Replies](https://developers.app.sinch.com/docs/api/replies/index.md) | Endpoints for checking and confirming inbound message replies (MO) received by your account. | ## Numbers | Service | Description | |---------|-------------| | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | The source address API provides several endpoints for you to request an SMS sender ID and track its approval status. | | [Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) | The number authorisation API allows you to manage your blacklists. Sinch automatically adds numbers to your blacklist if people send one of the opt-out keywords in response to one of your messages. | | [Dedicated Numbers](https://developers.app.sinch.com/docs/api/dedicated-numbers/index.md) | The Numbers API allows your to purchase, provision and configure the dedicated numbers assigned to your Sinch account. | ## Webhooks and security | Service | Description | |---------|-------------| | [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) | Webhooks Management API allows you to manage your webhooks configuration. You can subscribe to one or several events, retrieve the webhooks, update them or even delete them if needed. | | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | As a Sinch customer, you want to be able to ensure that webhooks are coming from Sinch and not from a 3rd party. | ## Reporting | Service | Description | |---------|-------------| | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | The Sinch Reports API provides a number of endpoints for running reports of messages sent and received through a Sinch Account. | | [Short Trackable Links Reports](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/index.md) | Short Trackable Links is a feature available to Messaging API users whereby it automatically and seamlessly shortens any URL to just 22 characters. | ## Contacts | Service | Description | |---------|-------------| | [Contacts](https://developers.app.sinch.com/docs/api/contacts/index.md) | The API provides access to two main resources: Contacts, Lists, and Custom Fields. | ## Accounts | Service | Description | |---------|-------------| | [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) | Create and delete reseller sub-accounts, and add Sinch Engage users for those accounts. | --- ### Source: docs/api/messages/cancel-scheduled-message.md # Cancel scheduled message Cancel a message that is still `scheduled` and has not yet been delivered, by setting `status` to `cancelled`. | | | |---|---| | **Service** | [Messages](https://developers.app.sinch.com/docs/api/messages/index.md) | | **Method** | `PUT` | | **URL** | `https://eu.app.api.sinch.com/v1/messages/{messageId}` | | **Operation ID** | `CancelScheduledMessage` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Message status updated successfully (no response body schema) | | **Required** | Path `messageId`; body `{ "status": "cancelled" }` | ### Request body ```json { "status": "cancelled" } ``` Only messages with status `scheduled` can be cancelled. Unknown `messageId` → `404`. Entity retention is 45 days. ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `messageId` | string | Yes | 36 character UUID. Example: `389dc1a8-62a4-4110-ba61-af94806c006f` | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string | Yes | Must be set to `cancelled`. | ### Example request body ```json { "status": "cancelled" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Message status updated successfully | — | | 400 | Bad request | `400response` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 200 response No response body schema is declared for this status. ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X PUT "https://eu.app.api.sinch.com/v1/messages/389dc1a8-62a4-4110-ba61-af94806c006f" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "status": "cancelled" }' ``` ### JavaScript (fetch) ```javascript const messageId = "389dc1a8-62a4-4110-ba61-af94806c006f"; const response = await fetch(`https://eu.app.api.sinch.com/v1/messages/${messageId}`, { method: "PUT", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ status: "cancelled" }) }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Bad request. Returned when the request body is invalid. - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. Returned when an invalid or nonexistent `messageId` is specified. Only messages with status `scheduled` can be cancelled. Message entities expire after 45 days. ## Related endpoints - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) - [Get message status](https://developers.app.sinch.com/docs/api/messages/get-message-status.md) ## Specification details Cancel a scheduled message that has not yet been delivered. A scheduled message can be cancelled by updating the status of a message from `scheduled` to `cancelled`. This is done by submitting a PUT request to the messages endpoint using the message ID as a parameter (the same endpoint used above to retrieve the status of a message). The expiry date for getting an entity is 45 days. The body of the request simply needs to contain a `status` property with the value set to `cancelled`. ```json { "status": "cancelled" } ``` *Note: Only messages with a status of scheduled can be cancelled. If an invalid or nonexistent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned* [← Messages](https://developers.app.sinch.com/docs/api/messages/index.md) --- ### Source: docs/api/messages/get-message-status.md # Get message status Retrieve the current status of a message using the `message_id` returned by [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md). Entities are retained for 45 days. | | | |---|---| | **Service** | [Messages](https://developers.app.sinch.com/docs/api/messages/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messages/{messageId}` | | **Operation ID** | `GetMessageStatus` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The submitted message including the status of the message | | **Required** | Path `messageId` (36-character UUID) | ### Example success body ```json { "format": "SMS", "content": "My first message!", "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "callback_url": "https://my.callback.url.com", "delivery_report": true, "destination_number": "+61401760575", "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570157", "source_number_type": "INTERNATIONAL", "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "status": "enroute" } ``` `status` is the current delivery state. See Delivery Reports documentation for status meanings. Invalid or unknown `messageId` → `404`. ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `messageId` | string | Yes | 36 character UUID. Example: `389dc1a8-62a4-4110-ba61-af94806c006f` | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The submitted message including the status of the message | `Getmessagestatusresponse` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `callback_url` | string | No | URL replies and delivery reports to this message will be pushed to | | `content` | string | No | Content of the message. Min length: 1. Max length: 5000. | | `destination_number` | string | No | Destination number of the message. Min length: 1. Max length: 15. | | `delivery_report` | boolean | No | Request a delivery report for this message | | `format` | string | No | Filter results by message format, using enumerable MessageType. Enum: `SMS`, `TTS`, `MMS` | | `message_expiry_timestamp` | string (date-time) | No | Date time after which the message expires and will not be sent | | `metadata` | object | No | Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long | | `scheduled` | string (date-time) | No | Scheduled delivery date time of the message | | `source_number` | string | No | | | `source_number_type` | string | No | Type of source address specified, this can be INTERNATIONAL, ALPHANUMERIC or SHORTCODE. Enum: `INTERNATIONAL`, `ALPHANUMERIC`, `SHORTCODE` | | `message_id` | string (uuid) | No | Unique ID of this message | | `status` | string | No | The status of the message. Enum: `undefined`, `queued`, `processing`, `processed`, `failed`, `scheduled`, `cancelled`, `delivered`, `expired`, `enroute`, `held`, `submitted`, `rejected`, `read` | Notes for implementers: - On this endpoint, `format` is the message’s channel (`SMS`, `TTS`, or `MMS`). The shared schema description also covers reporting filters. - `source_number` has no schema description in the OpenAPI component. ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messages/389dc1a8-62a4-4110-ba61-af94806c006f" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const messageId = "389dc1a8-62a4-4110-ba61-af94806c006f"; const response = await fetch(`https://eu.app.api.sinch.com/v1/messages/${messageId}`, { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const message = await response.json(); console.log(message.status); ``` ## Error handling - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. Returned when an invalid or nonexistent `messageId` is specified. Message status entities expire after 45 days. ## Related endpoints - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) - [Cancel scheduled message](https://developers.app.sinch.com/docs/api/messages/cancel-scheduled-message.md) ## Specification details Retrieve the current status of a message using the message ID returned in the send messages endpoint. A successful request to the get message status endpoint will return a response body as follows: ```json { "format": "SMS", "content": "My first message!", "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "callback_url": "https://my.callback.url.com", "delivery_report": true, "destination_number": "+61401760575", "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570157", "source_number_type": "INTERNATIONAL", "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "status": "enroute" } ``` The status property of the response indicates the current status of the message. See the Delivery Reports section of this documentation for more information on message statuses. The expiry date for getting an entity is 45 days. *Note: If an invalid or nonexistent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned* [← Messages](https://developers.app.sinch.com/docs/api/messages/index.md) --- ### Source: docs/api/messages/index.md # Messages The Sinch Messages API provides a number of endpoints for building powerful two-way messaging applications. The Messages API provides access to three main resources: * Messages - Messages delivered from an application to a handset. * Delivery Reports - Real time reports on the delivery status of a message. As a message is processed, it's status may change several times before it is finally delivered to a handset. * Replies - Messages sent from a handset to an application. These messages are typically a reply to a previously sent message. ![Message Flow](https://developers.app.sinch.com/docs/api/messages/message-flow.png) ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Submit SMS, MMS, or TTS for delivery (up to 100 per request) | [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) | | Look up current status by `message_id` (retained 45 days) | [Get message status](https://developers.app.sinch.com/docs/api/messages/get-message-status.md) | | Cancel a message that is still `scheduled` | [Cancel scheduled message](https://developers.app.sinch.com/docs/api/messages/cancel-scheduled-message.md) | ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) | `POST` | `/v1/messages` | Send messages | | [Get message status](https://developers.app.sinch.com/docs/api/messages/get-message-status.md) | `GET` | `/v1/messages/{messageId}` | Get message status | | [Cancel scheduled message](https://developers.app.sinch.com/docs/api/messages/cancel-scheduled-message.md) | `PUT` | `/v1/messages/{messageId}` | Cancel scheduled message | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/messages/send-messages.md # Send messages Submit one or more (up to 100 per request) SMS, MMS, or text-to-speech messages for delivery. | | | |---|---| | **Service** | [Messages](https://developers.app.sinch.com/docs/api/messages/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/messages` | | **Operation ID** | `SendMessages` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `202` — Messages were accepted for processing | | **Required body** | `messages[]` with `content` and `destination_number` on each item | ### Minimal request ```json { "messages": [ { "content": "My first message!", "destination_number": "+61491570156" } ] } ``` On success, each returned message includes `message_id` (UUID) and `status` (`queued`). Use [Get message status](https://developers.app.sinch.com/docs/api/messages/get-message-status.md) to poll later. If any message in the batch is invalid, **no** messages are sent. ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `messages` | array | Yes | List of messages. | ### `messages` item schema (`Message`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `content` | string | Yes | Content of the message. Min length: 1. Max length: 5000. | | `destination_number` | string | Yes | Destination number of the message. Min length: 1. Max length: 15. | | `callback_url` | string | No | URL replies and delivery reports to this message will be pushed to. Must use the `http` or `https` scheme. Hostnames must conform to RFC 1123 DNS name syntax. Paths must not contain whitespace or control characters. Invalid URLs are rejected with HTTP 400. | | `delivery_report` | boolean | No | Request a delivery report for this message | | `format` | string | No | Filter results by message format, using enumerable MessageType. Enum: `SMS`, `TTS`, `MMS` | | `message_expiry_timestamp` | string (date-time) | No | Date time after which the message expires and will not be sent | | `metadata` | object | No | Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long | | `scheduled` | string (date-time) | No | Scheduled delivery date time of the message | | `source_number` | string | No | | | `source_number_type` | string | No | Type of source address specified, this can be INTERNATIONAL, ALPHANUMERIC or SHORTCODE. Enum: `INTERNATIONAL`, `ALPHANUMERIC`, `SHORTCODE` | | `message_id` | string (uuid) | No | Unique ID of this message | | `status` | string | No | The status of the message. Enum: `undefined`, `queued`, `processing`, `processed`, `failed`, `scheduled`, `cancelled`, `delivered`, `expired`, `enroute`, `held`, `submitted`, `rejected`, `read` | | `media` | array of strings | No | The media is used to specify a list of URLs of the media file(s) that you are trying to send. Supported file formats include png, jpeg and gif. format parameter must be set to MMS for this to work. | | `subject` | string | No | The subject field is used to denote subject of the MMS message and has a maximum size of 64 characters long | Notes for implementers (schema cells above stay verbatim from the shared OpenAPI components): - On **this** endpoint, `format` selects the outbound channel. Use `SMS` (default), `MMS`, or `TTS`. The shared component description also appears on reporting filters. - `source_number` has no schema description; behaviour is documented under **Specification details** → Source number (sender ID). From 1-Mar-2024 the number or sender ID must be registered to your account. - `message_id` and `status` are response fields on the shared `Message` object. Do not send them on create; the API returns them. ### Example request body ```json { "messages": [ { "callback_url": "https://my.callback.url.com", "content": "My first message", "destination_number": "+61491570156", "delivery_report": true, "format": "SMS", "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "key1": "value1", "key2": "value2" }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570157", "source_number_type": "INTERNATIONAL" }, { "callback_url": "https://my.callback.url.com", "content": "My second message", "destination_number": "+61491570158", "delivery_report": true, "format": "MMS", "subject": "This is an MMS message", "media": [ "https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg" ], "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "key1": "value1", "key2": "value2" }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570159", "source_number_type": "INTERNATIONAL" } ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | Messages were accepted for processing | `Sendmessagesresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `400response` | | 401 | Unauthorized | `403response` | ### 202 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `messages` | array | No | List of messages. Max items: 100. | Each item uses the same `Message` schema as the request. On success the API populates `message_id` (36-character UUID) and `status` (`queued` at submission). See the request `Message` table above — it is not repeated here. ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 responses **Invalid destination number** ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "/messages/0/destination_number: International address must be between 8 and 15 characters excluding the first '+', International address contains invalid characters." ] } ``` **Invalid callback URL** ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "/messages/0/callbackUrl: Invalid callback url" ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messages" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "messages": [ { "content": "My first message!", "destination_number": "+61491570156" } ] }' ``` ### cURL (full example from the spec) ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messages" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "messages": [ { "callback_url": "https://my.callback.url.com", "content": "My first message", "destination_number": "+61491570156", "delivery_report": true, "format": "SMS", "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "key1": "value1", "key2": "value2" }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570157", "source_number_type": "INTERNATIONAL" }, { "callback_url": "https://my.callback.url.com", "content": "My second message", "destination_number": "+61491570158", "delivery_report": true, "format": "MMS", "subject": "This is an MMS message", "media": [ "https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg" ], "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "key1": "value1", "key2": "value2" }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570159", "source_number_type": "INTERNATIONAL" } ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messages", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ messages: [ { content: "My first message!", destination_number: "+61491570156" } ] }) }); const result = await response.json(); console.log(result.messages); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. Returned when the request fails to parse or message fields are invalid, including a malformed per-message `callback_url` (unsupported scheme, malformed hostname or DNS syntax, or path containing whitespace or control characters — e.g. `https://-invalid.com`, `https://invalid_.com`, `https:///path`, `https://:/path`, `http://.example.com`, `http://example..com`). If any message in a multi-message request is invalid, no messages are sent. Example detail: `"/messages/0/callbackUrl: Invalid callback url"`. - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - The operation description also notes HTTP **422** for Singapore (+65) destinations when the client does not use TLS 1.3 or higher (IMDA). That status is not declared on this operation’s `responses` map. ## Related endpoints - [Get message status](https://developers.app.sinch.com/docs/api/messages/get-message-status.md) - [Cancel scheduled message](https://developers.app.sinch.com/docs/api/messages/cancel-scheduled-message.md) ## Specification details Submit one or more (up to 100 per request) SMS, MMS or text to voice messages for delivery. The most basic message has the following structure: ```json { "messages": [ { "content": "My first message!", "destination_number": "+61491570156" } ] } ``` More advanced delivery features can be specified by setting the following properties in a message: - `callback_url` A URL can be included with each message to which Webhooks will be pushed to via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as it is processed (if the delivery report property of the request is set to `true`) and when replies are received. Specifying a callback URL is optional. When provided, the URL must use the `http` or `https` scheme, the hostname must conform to RFC 1123 DNS name syntax, and the path must not contain whitespace or control characters. Malformed values are rejected with HTTP 400. If any message in a multi-message request has an invalid `callback_url`, no messages are sent. - `content` The content of the message. This can be a Unicode string, up to 5,000 characters long. Message content is required. - `delivery_report` Delivery reports can be requested with each message. If delivery reports are requested, a webhook will be submitted to the `callback_url` property specified for the message (or to the webhooks) specified for the account every time the status of the message changes as it is processed. The current status of the message can also be retrieved via the Delivery Reports endpoint of the Messages API. Delivery reports are optional and by default will not be requested. - `destination_number` The destination number the message should be delivered to. This should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. A destination number is required. ⚠️ IMDA TLS Compliance Notice: From 1 April 2026, all requests sending messages to Singapore (+65) numbers must use TLS 1.3 or higher. Requests using an older TLS version will be rejected with HTTP 422 Unprocessable Entity. - `format` The format specifies which format the message will be sent as, `SMS` (text message), `MMS` (multimedia message) or `TTS` (text to speech). With `TTS` format, we will call the destination number and read out the message using a computer generated voice. Specifying a format is optional, by default `SMS` will be used. - `source_number_type` If a source number is specified, the type of source number may also be specified. This is recommended when using a source address type that is not an internationally formatted number, available options are `INTERNATIONAL`, `ALPHANUMERIC` or `SHORTCODE`. Specifying a source number type is only valid when the `source_number` parameter is specified and is optional. If a source number is specified and no source number type is specified, the source number type will be inferred from the source number, however this may be inaccurate. - `source_number`[optional] Specify a source number to be used. Refer to the section below for more information on source numbers. ⚠️ The number or sender ID must be registered to your account (from 1-Mar-2024). #### Source number (sender ID) There are several options for the number or sender ID that will show as the source of an outbound message. Some things to note: - If you do not specify a source number, the message will be sent with the default number for your account. - The default may be a number you have purchased from us - such as a dedicated number, a 10-digit longcode or toll-free number (US/CA), or a shortcode. Log into the web portal to manage your numbers. - If your account has multiple numbers, you can specify which source number to use in the request. - If your account does not have a number, your message may be sent using our shared number pool (in certain countries only) - `Alpha tag:` In some countries (AU, GB, some others), you may be able to send using an alpha tag - text that represents your brand of business. Before using an alpha tag, you must register it in the Numbers section of the web portal. - `Other numbers:` You may use numbers that you own as the source number, but you must register them in the Numbers section of the web portal to confirm you have a right to use the number. If you need to register a large number of source numbers/sender IDs, consider using our [Source Address API](https://developers.app.sinch.com/docs/api/source-address/index.md) ⚠️ If you specify a source_number that is not registered to your account, the message may fail to send, or may be sent with an alternative number. - `media` The media is used to specify a list of URLs of the media file(s) that you are trying to send. Supported file formats include png, jpeg and gif. `format` parameter must be set to `MMS` for this to work. - `subject` The subject field is used to denote subject of the MMS message and has a maximum size of 64 characters long. Specifying a subject is optional. - `scheduled` A message can be scheduled for delivery in the future by setting the scheduled property. The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. - `message_expiry_timestamp` A message expiry timestamp can be provided to specify the latest time at which the message should be delivered. If the message cannot be delivered before the specified message expiry timestamp elapses, the message will be discarded. Specifying a message expiry timestamp is optional. - `metadata` Metadata can be included with the message which will then be included with any delivery reports or replies matched to the message. This can be used to create powerful two-way messaging applications without having to store persistent data in the application. Up to 10 key / value metadata data pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to 256 characters long. Specifying metadata for a message is optional. The response body of a successful POST request to the messages endpoint will include a `messages` property which contains a list of all messages submitted. The list of messages submitted will reflect the list of messages included in the request, but each message will also contain two new properties, `message_id` and `status`. The returned message ID will be a 36 character UUID which can be used to check the status of the message via the Get Message Status endpoint. The status of the message which reflect the status of the message at submission time which will always be `queued`. See the Delivery Reports section of this documentation for more information on message statuses. *Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. If any messages in the request are invalid, no messages will be sent.* [← Messages](https://developers.app.sinch.com/docs/api/messages/index.md) --- ### Source: docs/api/messaging-reports/delete-scheduled-report.md # Delete scheduled report by id Deletes a scheduled report by providing its id. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/{id}` | | **Operation ID** | `DeleteScheduledReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `202` — An empty response indicating the report has been deleted. | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | The ID of the scheduled report to delete. | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | An empty response indicating the report has been deleted. | None | | 401 | No valid authentication details were provided | None | | 404 | Scheduled report not found. | None | ## Examples ### cURL (minimal) ```bash curl -X DELETE "https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e", { "method": "DELETE", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **401**: No valid authentication details were provided - **404**: Scheduled report not found. ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) ## Specification details Deletes a scheduled report by providing its id. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/detailscheduledreport.md # Scheduled detail report Create scheduled report in detail containing total number of sent, received and billing units. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled` | | **Operation ID** | `detailscheduledreport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `201` — A scheduled detail report received using the specified parameters. | | **Request body** | Required; `application/json` | ## Minimal request ```json { "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true ### scheduleddetailreport schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | Yes | The label of the report schedule | | | `schedule` | object | Yes | The time schedule of a scheduled report | | | `report` | object | Yes | A scheduled detail report request | | | `metadata` | array of object | No | Metadata for the message as a list of key/value pairs. Each key can be up to 100 characters long and each value can be up to 256 characters long.
```
[
{
"key": "myKey",
"value": "myValue"
},
{
"key": "anotherKey",
"value": "anotherValue"
}
]
``` | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled detail report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | No | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `message_format` | array of string | No | Format of message type. Deprecated — use the `channels` parameter instead, which provides equivalent and expanded message-type filtering. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | #### `metadata` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `key` | string | Yes | | | | `value` | string | Yes | | | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | A scheduled detail report received using the specified parameters. | `scheduledreportresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 201 response schema (`scheduledreportresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `scheduled_report_id` | string | No | The ID of the scheduled report. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) - [Update a scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/updatesummaryscheduledreport.md) ## Specification details Create scheduled report in detail containing total number of sent, received and billing units. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-active-report.md # Get active reports Retrieves all ACTIVE scheduled reports of a provided account. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/scheduled` | | **Operation ID** | `GetActiveReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — A list of all messages received in the specified time window | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `page_size` | number | No | Number of results to return in a page for paginated result sets. | Minimum: `1`; Maximum: `100` | | `page_token` | string | No | Returned by Chronos service | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of all messages received in the specified time window | `chronosscheduleresponse` | | 401 | No valid authentication details were provided | None | | 404 | Scheduled report not found. | None | ### 200 response schema (`chronosscheduleresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `pagination` | object | No | | | | `data` | array of object | No | | | #### `pagination` schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `page_token` | string | No | | | | `page_size` | number | No | Number of results to return in a page for paginated result sets. | | #### `data` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | No | The label of the report schedule | | | `report` | object | No | A scheduled summary report request | | | `schedule` | object | No | The time schedule of a scheduled report | | | `scheduled_report_id` | string | No | The ID of the scheduled report. | | | `message_type` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `report_type` | string | No | | | | `metadata` | object | No | Metadata for the scheduled report specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long. | | ##### `report` schema A scheduled summary report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | Yes | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out. | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ###### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | ##### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X GET "https://eu.app.api.sinch.com/v2-preview/reporting/scheduled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/scheduled", { "method": "GET", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **401**: No valid authentication details were provided - **404**: Scheduled report not found. ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) ## Specification details Retrieves all ACTIVE scheduled reports of a provided account. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-async-detail-fields.md # Get async detail fields Can be used for async detail report to select the fields to export csv files | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail/fields` | | **Operation ID** | `GetAsyncDetailFields` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — A list of selected fields to export csv files. | | **Request body** | Optional; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** false ### metakeyrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `page` | number | No | Page number for paging through paginated result sets. | | | `page_size` | number | No | Number of results to return in a page for paginated result sets. | | | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of selected fields to export csv files. | `fieldsresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`fieldsresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `fields` | array of string | No | An array of fields to be retrieved. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail/fields" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail/fields", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) - [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) - [Get async detail report status](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-status.md) ## Specification details Can be used for async detail report to select the fields to export csv files **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-async-detail-status.md # Get async detail report status Retrieves the status of a detail report. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/status` | | **Operation ID** | `GetAsyncDetailStatus` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — The status of the requested detail report. | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `report_id` | string | Yes | The ID of the detail report to retrieve. | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The status of the requested detail report. | `reportstatusresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`reportstatusresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `report_status` | string | No | | Enum: `REQUESTED`, `RUNNING`, `FAILED`, `CANCELLED`, `DONE` | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X GET "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/status?report_id=abc" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/status?report_id=abc", { "method": "GET", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) - [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) - [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) ## Specification details Retrieves the status of a detail report. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-async-report-download-url.md # Get async report download URL Returns a temporary pre-signed URL for downloading the generated report. The URL allows customers to securely download the report file directly using the provided reportId. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports/{reportId}/download-url` | | **Operation ID** | `GetAsyncReportDownloadUrl` | | **Authentication** | Basic Auth or HMAC Auth or Bearer JWT | | **Success** | `200` — A pre-signed URL for downloading the report. | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. - **Bearer JWT** (`bearer_auth`): Bearer JWT authentication used by selected messaging-reports async download endpoints. Prefer Basic or HMAC for all other operations. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `reportId` | string (uuid) | Yes | The ID of the report to download. | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A pre-signed URL for downloading the report. | `presignedurlresponse` | | 401 | No valid authentication details were provided | None | | 404 | Report not found. | `404response` | ### 200 response schema (`presignedurlresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `download_url` | string | No | The pre-signed URL for downloading the report file. | | | `file_name` | string | No | The filename of the report CSV. | | | `file_size` | integer (int64) | No | The size of the report file in bytes. | | | `expires_in_seconds` | integer | No | The number of seconds until the pre-signed URL expires. | | | `expires_at` | integer (int64) | No | Unix timestamp (seconds) when the pre-signed URL expires. | | ### 404 response schema (`404response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X GET "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports/51f0097f-90b2-4a59-ad88-a0fd93abaa82/download-url" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports/51f0097f-90b2-4a59-ad88-a0fd93abaa82/download-url", { "method": "GET", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **401**: No valid authentication details were provided - **404**: Report not found. ## Related endpoints - [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) - [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) - [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) ## Specification details Returns a temporary pre-signed URL for downloading the generated report. The URL allows customers to securely download the report file directly using the provided reportId. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-async-report-history.md # Get async report history Returns a list of asynchronous reports that have been requested by the current account. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports` | | **Operation ID** | `GetAsyncReportHistory` | | **Authentication** | Basic Auth or HMAC Auth or Bearer JWT | | **Success** | `200` — A list of async reports for the current account. | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. - **Bearer JWT** (`bearer_auth`): Bearer JWT authentication used by selected messaging-reports async download endpoints. Prefer Basic or HMAC for all other operations. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `page_size` | integer | No | The number of items to return per page. | | | `page_token` | string | No | A pagination token returned from a previous call. Pass this to retrieve the next page of results. | | | `report_name` | string | No | Filter results by report name. | | | `status` | array of string | No | Filter results by report status. Multiple statuses can be specified. | | | `start_date` | string (date-time) | No | Filter reports requested on or after this date (ISO 8601). | | | `end_date` | string (date-time) | No | Filter reports requested on or before this date (ISO 8601). | | | `sort_direction` | string | No | Sort direction for the results. | Enum: `ASCENDING`, `DESCENDING` | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of async reports for the current account. | `reporthistoryresponses` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`reporthistoryresponses`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `items` | array of object | No | A list of report history items. | | | `next_page_token` | string | No | A token to retrieve the next page of results. Absent if there are no more pages. | | #### `items` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `report_id` | string (uuid) | No | Unique identifier for the report. | | | `report_name` | string | No | The name of the report. | | | `report_type` | string | No | The type of the report. | Enum: `DETAIL`, `SUMMARY` | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `requested_by` | string | No | The UUID of the user who requested the report. | | | `requested_at` | string (date-time) | No | The date and time when the report was requested (ISO 8601). | | | `updated_at` | string (date-time) | No | The date and time when the report was last updated (ISO 8601). | | | `status` | string | No | The current status of the report. | Enum: `REQUESTED`, `RUNNING`, `FAILED`, `CANCELLED`, `DONE` | | `account_id` | string | No | The account ID associated with the report. | | | `vendor_id` | string | No | The vendor ID associated with the report. | | | `s3_file_size` | integer (int64) | No | The size of the report file in bytes. | | | `request_data` | object | No | The original report request parameters that were submitted, as an echo of the request body/query used to generate this report. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X GET "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/reports", { "method": "GET", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) - [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) - [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) ## Specification details Returns a list of asynchronous reports that have been requested by the current account. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/get-scheduled-report.md # Get scheduled report by id Retrieves a scheduled report by providing its id. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/{id}` | | **Operation ID** | `GetScheduledReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — The scheduled report matching the provided ID. | | **Request body** | None | ## Minimal request This operation has no request body. ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | The ID of the scheduled report to retrieve. | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The scheduled report matching the provided ID. | `scheduledreport` | | 401 | No valid authentication details were provided | None | | 404 | Scheduled report not found. | None | ### 200 response schema (`scheduledreport`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | No | The label of the report schedule | | | `report` | object | No | A scheduled summary report request | | | `schedule` | object | No | The time schedule of a scheduled report | | | `scheduled_report_id` | string | No | The ID of the scheduled report. | | | `message_type` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `report_type` | string | No | | | | `metadata` | object | No | Metadata for the scheduled report specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long. | | #### `report` schema A scheduled summary report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | Yes | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out. | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X GET "https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e", { "method": "GET", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json" } }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **401**: No valid authentication details were provided - **404**: Scheduled report not found. ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) ## Specification details Retrieves a scheduled report by providing its id. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/index.md # Messaging Reports Run synchronous, asynchronous, and scheduled reports for messages sent and received through a Sinch account. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Section | |------|---------| | Immediate detail / insight / metadata-key reports | [Synchronous detail and summary reports](#synchronous-detail-and-summary-reports) | | Long-running async reports, status, history, download | [Asynchronous reports](#asynchronous-reports) | | Recurring scheduled detail/summary reports | [Scheduled reports](#scheduled-reports) | ## Endpoints ### Synchronous detail and summary reports | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Post detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-detail-report.md) | `POST` | `/v2-preview/reporting/messages/detail` | Generates a report listing all sent and/or received messages within a specified time period. | | [Post insight report](https://developers.app.sinch.com/docs/api/messaging-reports/post-insight-report.md) | `POST` | `/v2-preview/reporting/messages/insights` | Create report summary containing total number of sent, received and billing units, using pre-calculated data to improve performance. | | [Metadata Keys](https://developers.app.sinch.com/docs/api/messaging-reports/post-metadata-keys.md) | `POST` | `/v2-preview/reporting/messages/metakeys` | Returns a list of metadata keys. | ### Asynchronous reports | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) | `POST` | `/v2-preview/reporting/messages/async/detail` | Generates an asynchronous report listing all sent and/or received messages within a specified time period. | | [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) | `POST` | `/v2-preview/reporting/messages/async/summary` | Creates an asynchronous report summary containing total number of sent, received and billing units. | | [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) | `POST` | `/v2-preview/reporting/messages/async/detail/fields` | Can be used for async detail report to select the fields to export csv files | | [Get async detail report status](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-status.md) | `GET` | `/v2-preview/reporting/messages/async/status` | Retrieves the status of a detail report. | | [Get async report history](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-report-history.md) | `GET` | `/v2-preview/reporting/messages/async/reports` | Returns a list of asynchronous reports that have been requested by the current account. | | [Get async report download URL](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-report-download-url.md) | `GET` | `/v2-preview/reporting/messages/async/reports/{reportId}/download-url` | Returns a temporary pre-signed URL for downloading the generated report. The URL allows customers to securely download the report file directly using the provided reportId. | ### Scheduled reports | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) | `POST` | `/v2-preview/reporting/detail/scheduled` | Create scheduled report in detail containing total number of sent, received and billing units. | | [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) | `POST` | `/v2-preview/reporting/summary/scheduled` | Create scheduled report summary containing total number of sent, received and billing units. | | [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) | `PUT` | `/v2-preview/reporting/detail/scheduled/{id}` | Updates a selected scheduled report in detail, which contains a total number of sent, received and billing units. | | [Update a scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/updatesummaryscheduledreport.md) | `PUT` | `/v2-preview/reporting/summary/scheduled/{id}` | Updates a selected scheduled report summary, which contains a total number of sent, received and billing units. | | [Get active reports](https://developers.app.sinch.com/docs/api/messaging-reports/get-active-report.md) | `GET` | `/v2-preview/reporting/scheduled` | Retrieves all ACTIVE scheduled reports of a provided account. | | [Get scheduled report by id](https://developers.app.sinch.com/docs/api/messaging-reports/get-scheduled-report.md) | `GET` | `/v2-preview/reporting/scheduled/{id}` | Retrieves a scheduled report by providing its id. | | [Delete scheduled report by id](https://developers.app.sinch.com/docs/api/messaging-reports/delete-scheduled-report.md) | `DELETE` | `/v2-preview/reporting/scheduled/{id}` | Deletes a scheduled report by providing its id. | ## Specification details The Sinch Reports API provides a number of endpoints for running reports of messages sent and received through
a Sinch Account. The API allows two kinds of reports, _Detailed Reports_ and _Summary Reports_.
Detailed reports list all messages and the details of each message sent or received in a specified time period. Summary reports allow inbound and outbound message data to be aggregated on a number of dimensions. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/messaging-reports/post-async-detail-report.md # Post async detail report Generates an asynchronous report listing all sent and/or received messages within a specified time period. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail` | | **Operation ID** | `PostAsyncDetailReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `202` — A list of all messages received in the specified time window | | **Request body** | Required; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true ### asyncsentmessagesdetailrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `timezone` | string | No | The timezone of the messages to include, using the name of the region. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. Can be used independently for searching. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. | | | `metadata_values` | array of string | No | Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `message_format` | array of string | No | Format of message type. Deprecated — use the `channels` parameter instead, which provides equivalent and expanded message-type filtering. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `sort_by` | string | No | Field to sort results set by | Enum: `FORMAT`, `DIRECTION`, `STATUS`, `SOURCE_ADDRESS`, `DESTINATION_ADDRESS`, `STATUS_CODE`, `ACCOUNT_ID`, `DESTINATION_ADDRESS_COUNTRY`, `SOURCE_ADDRESS_COUNTRY`, `TIMESTAMP` | | `sort_direction` | string | No | Order to sort results by. | Enum: `ASCENDING`, `DESCENDING` | | `period` | string | No | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `include_contacts` | boolean | No | Whether to include contact details in the report. | | | `account_names` | array of object | No | A list of account label overrides for the accounts included in the report. | | | `label` | string | No | A label for this report. | | | `user_id` | string | No | The ID of the user requesting the report. | | | `is_support` | boolean | No | Whether the report is being requested by support on behalf of the account. | | | `report_type` | string | No | The type of report being requested. | Enum: `DETAIL`, `SUMMARY`, `USER_USAGE`, `SUB_ACCOUNT_USAGE`, `GENERIC` | | `responded` | boolean | No | Filter results by whether the message received a response. | | | `fields` | array of object | No | Can be used for async detail report to select the fields to export csv files | | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | #### `account_names` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `account_id` | string | No | | | | `label` | string | No | | | #### `fields` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `name` | string | Yes | The `async/detail/fields` value from API. | | | `display_name` | string | Yes | Any string that you want to see in the CSV file header. | | #### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | A list of all messages received in the specified time window | `asyncreportresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 202 response schema (`asyncreportresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `report_id` | string | No | The ID of the returned report. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/detail", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post async summary report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-summary-report.md) - [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) - [Get async detail report status](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-status.md) ## Specification details Generates an asynchronous report listing all sent and/or received messages within a specified time period. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/post-async-summary-report.md # Post async summary report Creates an asynchronous report summary containing total number of sent, received and billing units. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/summary` | | **Operation ID** | `PostAsyncSummaryReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `202` — A list of all messages received in the specified time window | | **Request body** | Optional; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** false ### asyncsummaryrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `timezone` | string | No | The timezone of the messages to include, using the name of the region. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. Can be used independently for searching. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. | | | `metadata_values` | array of string | No | Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | A list of message statuses to filter the report by. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | #### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | A list of all messages received in the specified time window | `asyncreportresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 202 response schema (`asyncreportresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `report_id` | string | No | The ID of the returned report. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/summary" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/async/summary", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post async detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-async-detail-report.md) - [Get async detail fields](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-fields.md) - [Get async detail report status](https://developers.app.sinch.com/docs/api/messaging-reports/get-async-detail-status.md) ## Specification details Creates an asynchronous report summary containing total number of sent, received and billing units. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/post-detail-report.md # Post detail report Generates a report listing all sent and/or received messages within a specified time period. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/detail` | | **Operation ID** | `PostDetailReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — A list of all messages received in the specified time window | | **Request body** | Optional; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** false ### detailrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `timezone` | string | No | The timezone of the messages to include, using the name of the region. | | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `metadata_values` | array of string | No | Filter results for messages that include a metadata key containing these values. This parameter overrides the metadata_value property. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `mms_media` | boolean | No | Filter results by mms media. | | | `message_format` | array of string | No | Format of message type. Deprecated — use the `channels` parameter instead, which provides equivalent and expanded message-type filtering. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `page` | integer | No | Page number for paging through paginated result sets. | Minimum: `0` | | `page_size` | integer | No | Number of results to return in a page for paginated result sets. | Minimum: `1`; Maximum: `100` | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of all messages received in the specified time window | `detailresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`detailresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `messages` | array of object | No | | | | `pagination` | object | No | | | #### `messages` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message_id` | string (uuid) | No | Unique ID of this message | | | `format` | string | No | Filter results by message format, using enumerable MessageType. | Enum: `SMS`, `TTS`, `MMS` | | `timestamp` | string | No | Timestamp of this message | | | `delivered_timestamp` | string | No | Time that this message was delivered | | | `last_status_update` | string | No | Last time this message's status was updated | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `status` | string | No | The status of the message | Enum: `undefined`, `queued`, `processing`, `processed`, `failed`, `scheduled`, `cancelled`, `delivered`, `expired`, `enroute`, `held`, `submitted`, `rejected`, `read` | | `status_code` | number | No | The response code of the status | | | `status_description` | string | No | The status of the message | | | `source_address` | string | No | | | | `destination_address` | string | No | Destination number of the message | Min length: `1`; Max length: `15` | | `destination_address_country` | string | No | Country of the destination address | | | `source_address_country` | string | No | Country of the source address | | | `in_response_to` | string (uuid) | No | The ID of the message this message is a reply to, if any. | | | `action` | string | No | The action taken on the message, if any. | | | `media_url` | string | No | URL of the media attached to this message, if any (MMS/RCS). | | | `content` | string | No | Content of the message | Min length: `1`; Max length: `5000` | | `account_id` | string | No | The ID of the account | | | `units` | number | No | The amount of messages received | | | `billing_category` | string | No | The billing category applied to this RCS message (e.g. RCS_BASIC, RCS_SINGLE, RCS_RICH, RCS_RICH_MEDIA). Supported from 5/Feb/2026. This field is only available for RCS messages and only for messages sent on or after this date. | | | `message_type` | string | No | The type of rich message. Supported from 09/Sep/2025, and this data is available only for reports starting from this date. | Enum: `TEXT_MESSAGE`, `MEDIA_MESSAGE`, `LOCATION_MESSAGE`, `CHOICE_RESPONSE_MESSAGE`, `MEDIA_CARD_MESSAGE`, `CARD_MESSAGE`, `CAROUSEL_MESSAGE`, `CHOICE_MESSAGE` | | `metadata` | array of object | No | Metadata for the message as a list of key/value pairs. Each key can be up to 100 characters long and each value can be up to 256 characters long.
```
[
{
"key": "myKey",
"value": "myValue"
},
{
"key": "anotherKey",
"value": "anotherValue"
}
]
``` | | ##### `metadata` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `key` | string | Yes | | | | `value` | string | Yes | | | #### `pagination` schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `page` | number | No | | | | `page_size` | number | No | | | | `has_next` | boolean | No | | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/detail" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/detail", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post insight report](https://developers.app.sinch.com/docs/api/messaging-reports/post-insight-report.md) - [Metadata Keys](https://developers.app.sinch.com/docs/api/messaging-reports/post-metadata-keys.md) ## Specification details Generates a report listing all sent and/or received messages within a specified time period. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/post-insight-report.md # Post insight report Create report summary containing total number of sent, received and billing units, using pre-calculated data to improve performance. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/insights` | | **Operation ID** | `PostInsightReport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — A list of all messages received in the specified time window | | **Request body** | Optional; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T01:01:01.001z", "end_date": "2022-12-14T01:01:01.001z", "timezone": "Australia/Sydney" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** false ### insightsrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format and may include precise time values (e.g., milliseconds). | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date and may include precise time values (e.g., milliseconds). | | | `timezone` | string | Yes | The timezone of the messages to include, using the name of the region. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. Can be used independently for searching. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. | | | `metadata_values` | array of string | No | Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `channels` | array of string | No | Filter the report by one or more message channels. Supported from 14/Aug/2025, and filtering by channels is available only for reports starting from this date. | | | `group_by` | array of string | No | Defines available fields for grouping insights reports. COUNTRY and CHANNEL are supported from 14/Aug/2025, and POSTBACK_DATA is supported from 16/Sep/2025, with data available only from those dates onward. | | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of all messages received in the specified time window | `insightsresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`insightsresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `summaries` | array of object | No | | | | `total_sent` | number | No | | | | `total_received` | number | No | | | | `total_billing_units` | number | No | | | | `total_opt_out` | number | No | | | #### `summaries` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `group` | string | No | | | | `date` | string | No | One or more dates seperated by a comma, e.g. 2022-05-18,2022-05-19 | | | `total_sent` | number | No | | | | `total_received` | number | No | | | | `total_billing_units` | number | No | | | | `total_opt_out` | number | No | | | | `sub_groups` | array of object | No | | | ##### `sub_groups` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `date` | string | No | One or more dates separated by a comma, e.g. 2022-05-18,2022-05-19 | | | `group` | string | No | | | | `total_sent` | number | No | | | | `total_received` | number | No | | | | `total_billing_units` | number | No | | | | `total_opt_out` | number | No | | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/insights" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T01:01:01.001z", "end_date": "2022-12-14T01:01:01.001z", "timezone": "Australia/Sydney" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/insights", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T01:01:01.001z", "end_date": "2022-12-14T01:01:01.001z", "timezone": "Australia/Sydney" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Post detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-detail-report.md) - [Metadata Keys](https://developers.app.sinch.com/docs/api/messaging-reports/post-metadata-keys.md) ## Specification details Create report summary containing total number of sent, received and billing units, using pre-calculated data to improve performance. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/post-metadata-keys.md # Metadata Keys Returns a list of metadata keys. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/messages/metakeys` | | **Operation ID** | `PostMetadataKeys` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — A list of metadata keys. | | **Request body** | Optional; `application/json` | ## Minimal request ```json { "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** false ### metakeyrequest schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `page` | number | No | Page number for paging through paginated result sets. | | | `page_size` | number | No | Number of results to return in a page for paginated result sets. | | | `start_date` | string | Yes | Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `end_date` | string | Yes | End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of metadata keys. | `metakeyresponse` | | 400 | Bad Request. Check the json response for more details on what went wrong. | `400response` | | 401 | No valid authentication details were provided | None | ### 200 response schema (`metakeyresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `keys` | array of string | No | | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/messages/metakeys" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/messages/metakeys", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "start_date": "2022-12-12T00:00:00.000z", "end_date": "2022-12-14T00:00:00.000z" }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request. Check the json response for more details on what went wrong. - **401**: No valid authentication details were provided ## Related endpoints - [Post detail report](https://developers.app.sinch.com/docs/api/messaging-reports/post-detail-report.md) - [Post insight report](https://developers.app.sinch.com/docs/api/messaging-reports/post-insight-report.md) ## Specification details Returns a list of metadata keys. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/summaryscheduledreport.md # Scheduled summary report Create scheduled report summary containing total number of sent, received and billing units. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled` | | **Operation ID** | `summaryscheduledreport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `201` — A scheduled summary report received using the specified parameters. | | **Request body** | Required; `application/json` | ## Minimal request ```json { "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true ### scheduledsummaryreport schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | Yes | The label of the report schedule | | | `schedule` | object | Yes | The time schedule of a scheduled report | | | `report` | object | Yes | A scheduled summary report request | | | `metadata` | array of object | No | Metadata for the message as a list of key/value pairs. Each key can be up to 100 characters long and each value can be up to 256 characters long.
```
[
{
"key": "myKey",
"value": "myValue"
},
{
"key": "anotherKey",
"value": "anotherValue"
}
]
``` | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled summary report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | Yes | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out. | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | #### `metadata` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `key` | string | Yes | | | | `value` | string | Yes | | | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | A scheduled summary report received using the specified parameters. | `scheduledreportresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 201 response schema (`scheduledreportresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `scheduled_report_id` | string | No | The ID of the scheduled report. | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X POST "https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled", { "method": "POST", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) - [Update a scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/updatesummaryscheduledreport.md) ## Specification details Create scheduled report summary containing total number of sent, received and billing units. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/updatedetailscheduledreport.md # Update a scheduled detail report Updates a selected scheduled report in detail, which contains a total number of sent, received and billing units. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `PUT` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled/{id}` | | **Operation ID** | `updatedetailscheduledreport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — The updated scheduled detail report. | | **Request body** | Required; `application/json` | ## Minimal request ```json { "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | The ID of the scheduled report to update. | | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true ### updatescheduleddetailreport schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | Yes | The label of the report schedule | | | `schedule` | object | Yes | The time schedule of a scheduled report | | | `report` | object | Yes | A scheduled detail report request | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled detail report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | No | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `message_format` | array of string | No | Format of message type. Deprecated — use the `channels` parameter instead, which provides equivalent and expanded message-type filtering. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The updated scheduled detail report. | `scheduleddetailreportresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`scheduleddetailreportresponse`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | No | The label of the report schedule | | | `schedule` | object | No | The time schedule of a scheduled report | | | `report` | object | No | A scheduled detail report request | | | `scheduled_report_id` | string | No | The ID of the scheduled report. | | | `message_type` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `report_type` | string | No | | | | `metadata` | array of object | No | Metadata for the message as a list of key/value pairs. Each key can be up to 100 characters long and each value can be up to 256 characters long.
```
[
{
"key": "myKey",
"value": "myValue"
},
{
"key": "anotherKey",
"value": "anotherValue"
}
]
``` | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled detail report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | No | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `message_format` | array of string | No | Format of message type. Deprecated — use the `channels` parameter instead, which provides equivalent and expanded message-type filtering. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out | | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | #### `metadata` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `key` | string | Yes | | | | `value` | string | Yes | | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X PUT "https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/detail/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e", { "method": "PUT", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK" } }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/updatesummaryscheduledreport.md) ## Specification details Updates a selected scheduled report in detail, which contains a total number of sent, received and billing units. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/messaging-reports/updatesummaryscheduledreport.md # Update a scheduled summary report Updates a selected scheduled report summary, which contains a total number of sent, received and billing units. | | | |---|---| | **Service** | [Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) | | **Method** | `PUT` | | **URL** | `https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled/{id}` | | **Operation ID** | `updatesummaryscheduledreport` | | **Authentication** | Basic Auth or HMAC Auth | | **Success** | `200` — The updated scheduled summary report. | | **Request body** | Required; `application/json` | ## Minimal request ```json { "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } } ``` ## Authentication The operation declares these authentication alternatives (each item in the OpenAPI security array is an **OR** choice): - **Basic Auth** (`basic_auth`): HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth** (`hmac_auth`): HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Base URLs | Region | URL | |--------|-----| | EU | `https://eu.app.api.sinch.com` | | APAC | `https://au.app.api.sinch.com` | ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | The ID of the scheduled report to update. | | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true ### updatescheduledsummaryreport schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | Yes | The label of the report schedule | | | `schedule` | object | Yes | The time schedule of a scheduled report | | | `report` | object | Yes | A scheduled summary report request | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled summary report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | Yes | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out. | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The updated scheduled summary report. | `scheduledsummaryreportresposne` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema (`scheduledsummaryreportresposne`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | No | The label of the report schedule | | | `schedule` | object | No | The time schedule of a scheduled report | | | `report` | object | No | A scheduled summary report request | | | `scheduled_report_id` | string | No | The ID of the scheduled report. | | | `message_type` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `report_type` | string | No | | | | `metadata` | array of object | No | Metadata for the message as a list of key/value pairs. Each key can be up to 100 characters long and each value can be up to 256 characters long.
```
[
{
"key": "myKey",
"value": "myValue"
},
{
"key": "anotherKey",
"value": "anotherValue"
}
]
``` | | #### `schedule` schema The time schedule of a scheduled report | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `timezone` | string | Yes | The timezone of the report. | | | `cron_expression` | string | Yes | A string consisting of six or seven subexpressions that describe individual details of the schedule. | | | `type` | string | Yes | | | #### `report` schema A scheduled summary report request | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `period` | string | Yes | Automatically set a date range based on the period value. Can't be combined with start_date and end_date. | Enum: `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_30_DAYS`, `LAST_7_DAYS`, `THIS_WEEKDAYS`, `LAST_WEEKDAYS` | | `timezone` | string | Yes | The standard timezone name | | | `direction` | string | No | The type of messages to include in the report. | Enum: `inbound`, `outbound`, `all` | | `source` | string | No | Filter results by source address. | | | `sources` | array of string | No | Filter results by multiple source addresses. This property overrides the `source` parameter. | | | `destination` | string | No | Filter results by destination address. | | | `destinations` | array of string | No | Filter results by multiple destination addresses. This property overrides the `destination` parameter. | | | `addresses` | array of string | No | Filter messages where source OR destination matches one of the provided values. This parameter can only be set when `direction` is `all` and cannot be used in the same request as the `source`, `destination`, `sources`, or `destinations` parameters. | | | `channels` | array of string | No | Filter the report by one or more channels. | | | `metadata_key` | string | No | Filter results for messages that include a metadata key. | | | `metadata_value` | string | No | Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. | | | `accounts` | array of string | No | Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. | | | `status` | array of string | No | An array of message statuses. | | | `opt_out` | boolean | No | Filter the report to only include messages that triggered an opt-out. | | | `group_by` | array of string | No | Group results by a list of values, from the enumerable table above. | | | `account_activity` | string | No | Filter accounts included in the report by activity level. | Enum: `ALL`, `COLD`, `ACTIVE` | | `delivery_options` | array of object | No | A list of options to configure the delivery of the report. | | ##### `delivery_options` item schema A delivery option | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `delivery_type` | string | No | How to deliver the report. | Enum: `EMAIL` | | `delivery_addresses` | array of string | No | A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type | | | `delivery_format` | string | No | Format of the report. | Enum: `CSV` | #### `metadata` item schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `key` | string | Yes | | | | `value` | string | Yes | | | ### 400 response schema (`400response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### 401 response schema (`403response`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ## Examples ### cURL (minimal) ```bash curl -X PUT "https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v2-preview/reporting/summary/scheduled/e6fb8282-c7c3-4367-8590-6c77ddb11c3e", { "method": "PUT", "headers": { "Authorization": "Basic BASE64_ENCODED_CREDENTIALS", "Accept": "application/json", "Content-Type": "application/json" }, "body": JSON.stringify({ "label": "Weekly Report", "schedule": { "timezone": "UTC", "cron_expression": "0 0 * * * ? *", "type": "cron" }, "report": { "period": "THIS_WEEK", "timezone": "Australia/Sydney" } }) }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } const result = response.status === 204 ? null : await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized ## Related endpoints - [Scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/detailscheduledreport.md) - [Scheduled summary report](https://developers.app.sinch.com/docs/api/messaging-reports/summaryscheduledreport.md) - [Update a scheduled detail report](https://developers.app.sinch.com/docs/api/messaging-reports/updatedetailscheduledreport.md) ## Specification details Updates a selected scheduled report summary, which contains a total number of sent, received and billing units. **Request body description:** Request body. [← Messaging Reports](https://developers.app.sinch.com/docs/api/messaging-reports/index.md) --- ### Source: docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md # Add one or more numbers to your blacklist Add up to 10 numbers to your account's blacklist in one request. | | | |---|---| | **Service** | [Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/number_authorisation/mt/blacklist` | | **Operation ID** | `AddOneOrMoreNumbersToYourBlacklist` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — If all the numbers are already on the blacklist, then a 200 is returned. | | **Required body** | `numbers` | ### Minimal request ```json { "numbers": [ "61491570156" ] } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Description:** Request body. - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `numbers` | array of strings | Yes | Array of numbers to be added to the blacklist. These should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. | ### Example request body ```json { "numbers": [ "61491570156", "61491570157" ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | If all the numbers are already on the blacklist, then a 200 is returned. | `Addoneormorenumberstoyourblacklistresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 201 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `uri` | string | Yes | | | `numbers` | array of strings | Yes | List of phone numbers. | ### Example 201 response ```json { "uri": "/v1/number_authorisation/mt/blacklist", "numbers": [ "61491570156", "61491570157" ] } ``` ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples ### cURL ```bash API_KEY="YOUR_API_KEY" API_SECRET="YOUR_API_SECRET" API_HOST="https://eu.app.api.sinch.com" BASIC_AUTH=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64 | tr -d '\n') curl -sS -X POST "${API_HOST}/v1/number_authorisation/mt/blacklist" \ -H "Authorization: Basic ${BASIC_AUTH}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "numbers": [ "61491570156", "61491570157" ] }' ``` ### JavaScript (fetch) ```javascript const apiKey = 'YOUR_API_KEY'; const apiSecret = 'YOUR_API_SECRET'; const apiHost = 'https://eu.app.api.sinch.com'; const auth = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64'); const response = await fetch(`${apiHost}/v1/number_authorisation/mt/blacklist`, { method: 'POST', headers: { Authorization: `Basic ${auth}`, Accept: 'application/json', 'Content-Type': 'application/json', }, body: JSON.stringify({ numbers: [ '61491570156', '61491570157', ], }), }); console.log(response.status); console.log(await response.json()); ``` ## Error handling - **400 Bad Request**: Bad Request. Check the JSON request body. - **401 Unauthorized**: Unauthorized. Verify the authentication credentials on the request. ## Related endpoints - [List all blocked numbers](https://developers.app.sinch.com/docs/api/number-authorisation/list-all-blocked-numbers.md) - [Remove a number from the blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/remove-a-number-from-the-blacklist.md) - [Check if one or several numbers are currently blacklisted](https://developers.app.sinch.com/docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md) ## Specification details This endpoint allows you to add one or more numbers to your blacklist. You can add up to 10 numbers in one request. NOTE: numbers need to be in international format and therefore start with a + [← Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) --- ### Source: docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md # Check if one or several numbers are currently blacklisted Check whether your account is authorised to send messages to one or more numbers before attempting a send. | | | |---|---| | **Service** | [Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/number_authorisation/is_authorised/{numbers}` | | **Operation ID** | `CheckIfOneOrSeveralNumbersAreCurrentlyBlacklisted` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Successful response. | | **Required** | `numbers` path parameter | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `numbers` | array of strings | Yes | one or more numbers in international format separated by a comma, e.g. ```+61491570156,+61491570157``` | Minimum: 1 | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Successful response. | `Checkifoneorseveralnumbersarecurrentlyblacklistedresponse` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | `403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `uri` | string | Yes | | | `numbers` | array of `Number` | Yes | List of phone numbers. | #### `numbers` item schema (`Number`) Number authorisation result for a single phone number | Property | Type | Required | Description | |----------|------|----------|-------------| | `number` | string | Yes | Phone number as a string | | `authorised` | boolean | Yes | Whether the authenticated account is authorised to use this number | ### Example 200 response ```json { "uri": "/v1/number_authorisation/is_authorised/+61491570156,+61491570157", "numbers": [ { "number": "+61491570156", "authorised": true }, { "number": "+61491570157", "authorised": false } ] } ``` ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples ### cURL ```bash API_KEY="YOUR_API_KEY" API_SECRET="YOUR_API_SECRET" API_HOST="https://eu.app.api.sinch.com" NUMBERS="+61491570156,+61491570157" BASIC_AUTH=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64 | tr -d '\n') curl -sS -X GET "${API_HOST}/v1/number_authorisation/is_authorised/${NUMBERS}" \ -H "Authorization: Basic ${BASIC_AUTH}" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const apiKey = 'YOUR_API_KEY'; const apiSecret = 'YOUR_API_SECRET'; const apiHost = 'https://eu.app.api.sinch.com'; const numbers = '+61491570156,+61491570157'; const auth = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64'); const response = await fetch(`${apiHost}/v1/number_authorisation/is_authorised/${numbers}`, { method: 'GET', headers: { Authorization: `Basic ${auth}`, Accept: 'application/json', }, }); console.log(response.status); console.log(await response.json()); ``` ## Error handling - **400 Bad Request**: Bad Request. Check the `numbers` path value. - **401 Unauthorized**: Unauthorized. Verify the authentication credentials on the request. ## Related endpoints - [List all blocked numbers](https://developers.app.sinch.com/docs/api/number-authorisation/list-all-blocked-numbers.md) - [Add one or more numbers to your blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md) - [Remove a number from the blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/remove-a-number-from-the-blacklist.md) ## Specification details This endpoint lists for each requested number if you are authorised (which means the number is not blacklisted) to send to this number. In the example given +61491570157 is on the blacklist. NOTE: We do this call for you internally no matter what. Use this endpoint only if you want to have some indication upfront. If you send a message which is on the blacklist, we issue a delivery receipt with the appropriate status code. [← Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) --- ### Source: docs/api/number-authorisation/index.md # Number Authorisation Manage the numbers your account must not message, check authorisation before sending, and review the current blacklist. Sinch can add numbers automatically when recipients reply with opt-out keywords. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Check whether one or more numbers are authorised for messaging | [Check if one or several numbers are currently blacklisted](https://developers.app.sinch.com/docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md) | | Review the blacklist, 100 numbers at a time | [List all blocked numbers](https://developers.app.sinch.com/docs/api/number-authorisation/list-all-blocked-numbers.md) | | Add up to 10 numbers to the blacklist | [Add one or more numbers to your blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md) | | Remove one number from the blacklist | [Remove a number from the blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/remove-a-number-from-the-blacklist.md) | ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Check if one or several numbers are currently blacklisted](https://developers.app.sinch.com/docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md) | `GET` | `/v1/number_authorisation/is_authorised/{numbers}` | Check if one or several numbers are currently blacklisted | | [List all blocked numbers](https://developers.app.sinch.com/docs/api/number-authorisation/list-all-blocked-numbers.md) | `GET` | `/v1/number_authorisation/mt/blacklist` | List all blocked numbers | | [Add one or more numbers to your blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md) | `POST` | `/v1/number_authorisation/mt/blacklist` | Add one or more numbers to your blacklist | | [Remove a number from the blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/remove-a-number-from-the-blacklist.md) | `DELETE` | `/v1/number_authorisation/mt/blacklist/{number}` | Remove a number from the blacklist | ## Specification details The number authorisation API allows you to manage your blacklists. Sinch automatically adds numbers to your blacklist if people send one of the opt-out keywords in response to one of your messages. This is a legal requirement. If you decide to handle the legal compliance yourself, calls to this endpoint will not affect your messages. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/number-authorisation/list-all-blocked-numbers.md # List all blocked numbers Retrieve the numbers on your account's blacklist in pages of up to 100 entries. | | | |---|---| | **Service** | [Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/number_authorisation/mt/blacklist` | | **Operation ID** | `ListAllBlockedNumbers` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Number authorisation blacklist was returned successfully. | | **Optional** | `token` query parameter | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `token` | string | No | Opaque pagination token from a previous response. Omit on the first request. Pass the returned token to retrieve the next page of up to 100 numbers. | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Number authorisation blacklist was returned successfully. | `Getnumberauthorisationblacklistresponse` | | 401 | Unauthorized | `403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `uri` | string | No | URL of the current API call, used to show the current pagination token for calls subsequent to the first one in the case of paginated data. | | `numbers` | array of strings | No | List of numbers belonging to the blacklist. | | `pagination` | `Pagination` | No | | #### `pagination` schema (`Pagination`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `page` | string | No | The pagination token of the next set of results. | | `next_uri` | string | No | The uri pointing to the next set of results. | ### Example 200 response ```json { "uri": "/v1/number_authorisation/mt/blacklist\"", "numbers": [ "+61491570156", "+61491570157" ], "pagination": { "page": "0", "next_uri": "/v1/number_authorisation/mt/blacklist?token=0" } } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples Omit `token` on the first request. For a subsequent page, pass the token returned in `pagination.page`. ### cURL ```bash API_KEY="YOUR_API_KEY" API_SECRET="YOUR_API_SECRET" API_HOST="https://eu.app.api.sinch.com" TOKEN="eyJwYWdlIjoyfQ" BASIC_AUTH=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64 | tr -d '\n') curl -sS -X GET "${API_HOST}/v1/number_authorisation/mt/blacklist?token=${TOKEN}" \ -H "Authorization: Basic ${BASIC_AUTH}" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const apiKey = 'YOUR_API_KEY'; const apiSecret = 'YOUR_API_SECRET'; const apiHost = 'https://eu.app.api.sinch.com'; const token = 'eyJwYWdlIjoyfQ'; const auth = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64'); const response = await fetch(`${apiHost}/v1/number_authorisation/mt/blacklist?token=${token}`, { method: 'GET', headers: { Authorization: `Basic ${auth}`, Accept: 'application/json', }, }); console.log(response.status); console.log(await response.json()); ``` ## Error handling - **401 Unauthorized**: Unauthorized. Verify the authentication credentials on the request. ## Related endpoints - [Check if one or several numbers are currently blacklisted](https://developers.app.sinch.com/docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md) - [Add one or more numbers to your blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md) - [Remove a number from the blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/remove-a-number-from-the-blacklist.md) ## Specification details This endpoint returns a list of 100 numbers that are on the blacklist. There is a pagination token to retrieve the next 100 numbers In the example response the numbers `+61491570156` and `+61491570157` are on the blacklist and therefore will never receive any messages from you. [← Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) --- ### Source: docs/api/number-authorisation/remove-a-number-from-the-blacklist.md # Remove a number from the blacklist Remove one number from your account's blacklist. | | | |---|---| | **Service** | [Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/number_authorisation/mt/blacklist/{number}` | | **Operation ID** | `RemoveANumberFromTheBlacklist` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The number has been successfully deleted. | | **Required** | `number` path parameter | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `number` | string | Yes | a number in international format e.g. ```+61491570156``` | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The number has been successfully deleted. | string (binary), `text/plain` | | 401 | No valid authentication details were provided | None | | 404 | Not found. | None | ### 200 response schema - **Content-Type:** `text/plain` - **Type:** string - **Format:** binary - **Description:** The number has been successfully deleted. No response properties are declared. ## Examples ### cURL ```bash API_KEY="YOUR_API_KEY" API_SECRET="YOUR_API_SECRET" API_HOST="https://eu.app.api.sinch.com" NUMBER="+61491570156" BASIC_AUTH=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64 | tr -d '\n') curl -sS -X DELETE "${API_HOST}/v1/number_authorisation/mt/blacklist/${NUMBER}" \ -H "Authorization: Basic ${BASIC_AUTH}" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const apiKey = 'YOUR_API_KEY'; const apiSecret = 'YOUR_API_SECRET'; const apiHost = 'https://eu.app.api.sinch.com'; const number = '+61491570156'; const auth = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64'); const response = await fetch(`${apiHost}/v1/number_authorisation/mt/blacklist/${number}`, { method: 'DELETE', headers: { Authorization: `Basic ${auth}`, Accept: 'application/json', }, }); console.log(response.status); console.log(await response.text()); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Add valid authentication details to the request. - **404 Not Found**: Not found. No blacklist entry matches the supplied `number`. ## Related endpoints - [Add one or more numbers to your blacklist](https://developers.app.sinch.com/docs/api/number-authorisation/add-one-or-more-numbers-to-your-blacklist.md) - [List all blocked numbers](https://developers.app.sinch.com/docs/api/number-authorisation/list-all-blocked-numbers.md) - [Check if one or several numbers are currently blacklisted](https://developers.app.sinch.com/docs/api/number-authorisation/check-if-one-or-several-numbers-are-currently-blacklisted.md) ## Specification details This endpoint allows you to remove a number from the blacklist. Only one number can be deleted per request. In the example +61491570157 will be removed from the blacklist. NOTE: numbers need to be in international format and therefore start with a + [← Number Authorisation](https://developers.app.sinch.com/docs/api/number-authorisation/index.md) --- ### Source: docs/api/replies/check-replies.md # Check replies Return unconfirmed inbound replies (MO) for the account. Max 100 per response. Same replies repeat until confirmed. Prefer [Webhooks](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) over polling when possible. Retention: 45 days. | | | |---|---| | **Service** | [Replies](https://developers.app.sinch.com/docs/api/replies/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/replies` | | **Operation ID** | `CheckReplies` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Unconfirmed replies | | **Required** | None (no path, query, or body parameters) | ### Poll pattern 1. Call this endpoint. 2. Process each `replies[]` item. 3. Confirm IDs with [Confirm replies as received](https://developers.app.sinch.com/docs/api/replies/confirm-replies-as-received.md). ### Example success body ```json { "replies": [ { "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74", "date_received": "2016-12-07T08:43:00.850Z", "callback_url": "https://my.callback.url.com", "destination_number": "+61491570156", "source_number": "+61491570157", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "content": "My first reply!" } ] } ``` Note: In a reply, source and destination numbers are inverted relative to the original outbound message. If the original message had no `source_number`, `destination_number` may be absent on the reply. ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Unconfirmed replies | `Checkrepliesresponse` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `replies` | array | No | The oldest 100 unconfirmed replies. Min items: 0. Max items: 100. | #### `replies` item schema (`Reply`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `callback_url` | string | No | The URL specified as the callback URL in the original submit message request | | `content` | string | No | Content of the reply. Min length: 1. Max length: 5000. | | `date_received` | string (date-time) | No | Date time when the reply was received | | `destination_number` | string | No | Address from which this reply was sent to. Min length: 1. Max length: 15. | | `message_id` | string (uuid) | No | Unique ID of the original message | | `metadata` | object | No | Any metadata that was included in the original submit message request | | `reply_id` | string (uuid) | No | Unique ID of this reply | | `source_number` | string | No | Address from which this reply was received from. Min length: 1. Max length: 15. | | `vendor_account_id` | object | No | | ##### `vendor_account_id` schema (`VendorAccountId`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `vendor_id` | string | No | | | `account_id` | string | No | The account used to submit the original message. | ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/replies" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/replies", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result.replies); ``` ## Error handling - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. ## Related endpoints - [Confirm replies as received](https://developers.app.sinch.com/docs/api/replies/confirm-replies-as-received.md) - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) - [Check delivery reports](https://developers.app.sinch.com/docs/api/delivery-reports/check-delivery-reports.md) ## Specification details Check for any replies that have been received. Replies are messages that have been sent from a handset in response to a message sent by an application or messages that have been sent from a handset to a inbound number associated with an account, known as a dedicated inbound number (contact for more information on dedicated inbound numbers). Each request to the check replies endpoint will return any replies received that have not yet been confirmed using the confirm replies endpoint. A response from the check replies endpoint will have the following structure: ```json { "replies": [ { "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74", "date_received": "2016-12-07T08:43:00.850Z", "callback_url": "https://my.callback.url.com", "destination_number": "+61491570156", "source_number": "+61491570157", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "content": "My first reply!" }, { "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4", "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f", "date_received": "2016-12-07T08:43:00.850Z", "callback_url": "https://my.callback.url.com", "destination_number": "+61491570157", "source_number": "+61491570158", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "content": "My second reply!" } ] } ``` Each reply will contain details about the reply message, as well as details of the message the reply was sent in response to, including any metadata specified. Every reply will have a reply ID to be used with the confirm replies endpoint. *Note: The source number and destination number properties in a reply are the inverse of those specified in the message the reply is in response to. The source number of the reply message is the same as the destination number of the original message, and the destination number of the reply message is the same as the source number of the original message. If a source number wasn't specified in the original message, then the destination number property will not be present in the reply message.* Subsequent requests to the check replies endpoint will return the same reply messages and a maximum of 100 replies will be returned in each request. Applications should use the confirm replies endpoint in the following pattern so that replies that have been processed are no longer returned in subsequent check replies requests. The expiry date for getting an entity is 45 days. 1. Call check replies endpoint 2. Process each reply message 3. Confirm all processed reply messages using the confirm replies endpoint *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check replies endpoint.* [← Replies](https://developers.app.sinch.com/docs/api/replies/index.md) --- ### Source: docs/api/replies/confirm-replies-as-received.md # Confirm replies as received Mark replies as confirmed so they are no longer returned by [Check replies](https://developers.app.sinch.com/docs/api/replies/check-replies.md). Up to 100 IDs per request. Retention: 45 days. | | | |---|---| | **Service** | [Replies](https://developers.app.sinch.com/docs/api/replies/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/replies/confirmed` | | **Operation ID** | `ConfirmRepliesAsReceived` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `202` — Requested replies will be marked as confirmed | | **Required body** | `reply_ids` (array of UUIDs, max 100) | ### Minimal request ```json { "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d" ] } ``` Confirm **reply** UUIDs, not the original message UUIDs. ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `reply_ids` | array of string (uuid) | Yes | The UUID of the *reply* to be confirmed (note: not the UUID of the message it is in response to). Max items: 100. | ### Example request body ```json { "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | Requested replies will be marked as confirmed | object (`text/plain`) | | 400 | Bad request | `400response` | | 401 | Unauthorized | `403response` | | 404 | Resource not found | `404response` | ### 202 response schema - **Content-Type:** `text/plain` - **Schema:** `type: object` - **Description:** Requested replies will be marked as confirmed No properties are declared on this response schema. ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 401 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 401 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/replies/confirmed" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/replies/confirmed", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ reply_ids: [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] }) }); console.log(response.status); ``` ## Error handling - **400 Bad Request**: Bad request. Returned when the request body is invalid. - **401 Unauthorized**: Unauthorized. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Resource not found. ## Related endpoints - [Check replies](https://developers.app.sinch.com/docs/api/replies/check-replies.md) ## Specification details Mark a reply message as confirmed so it is no longer returned in check replies requests. The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint to allow for robust processing of reply messages. Once one or more reply messages have been processed they can then be confirmed using the confirm replies endpoint so they are no longer returned in subsequent check replies requests. The confirm replies endpoint takes a list of reply IDs as follows: ```json { "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` The expiry date for getting an entity is 45 days. Up to 100 replies can be confirmed in a single confirm replies request. [← Replies](https://developers.app.sinch.com/docs/api/replies/index.md) --- ### Source: docs/api/replies/index.md # Replies Endpoints for checking and confirming inbound message replies (MO) received by your account. Polling returns unconfirmed replies (max 100). Prefer [Webhooks](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) over polling when possible. Entity retention is 45 days. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Fetch up to 100 unconfirmed replies | [Check replies](https://developers.app.sinch.com/docs/api/replies/check-replies.md) | | Mark processed reply IDs so they stop returning (up to 100 per call) | [Confirm replies as received](https://developers.app.sinch.com/docs/api/replies/confirm-replies-as-received.md) | Recommended poll pattern: check → process → confirm. Repeat until empty. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Check replies](https://developers.app.sinch.com/docs/api/replies/check-replies.md) | `GET` | `/v1/replies` | Check replies | | [Confirm replies as received](https://developers.app.sinch.com/docs/api/replies/confirm-replies-as-received.md) | `POST` | `/v1/replies/confirmed` | Confirm replies as received | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/short-trackable-links-reports/index.md # Short Trackable Links Reports Short Trackable Links is a feature available to [Messaging API](https://support.app.sinch.com/hc/en-us/categories/10516535548943-Sinch-Engage-Developer-Guides) users whereby it automatically and seamlessly shortens any URL to just 22 characters. Every shortened URL is unique to each recipient. The reporting API has endpoints specific to this feature, allowing users to obtain details regarding the number of click-throughs on each URL. To enable this feature on your account, contact your account manager or contact support on [support@app.sinch.com](mailto:support@app.sinch.com). To learn more about the benefits of the Short Trackable Links feature, [visit our feature page](https://support.app.sinch.com/hc/en-us/articles/10525004171919-Short-Trackable-Links-URL-shortener). ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Inspect click and view events for one short URL hash | [Log detail](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-detail.md) | | Aggregate short URL activity using optional metadata, URL, or recipient filters | [Log summary](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-summary.md) | Use **Log summary** to discover aggregate activity and matching short URLs. Use **Log detail** when you have a short URL `hash` and need its individual click and view events. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Log detail](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-detail.md) | `GET` | `/v1/reporting/links/detail` | Log detail | | [Log summary](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-summary.md) | `GET` | `/v1/reporting/links/summary` | Log summary | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/short-trackable-links-reports/log-detail.md # Log detail Retrieve the individual click and view events recorded for a short trackable URL hash. Detailed clicks report for a hashcode. | | | |---|---| | **Service** | [Short Trackable Links Reports](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/reporting/links/detail` | | **Operation ID** | `LogDetail` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | Query parameter: `hash` | ### Minimal request ```text GET /v1/reporting/links/detail?hash= ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `hash` | string | Yes | Short URL hash code to retrieve click detail for. | | `page` | number (double) | No | Page number for pagination (1-based). | | `pageSize` | number (double) | No | Number of results per page. | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `LogsDetailResult` | | 400 | Bad Request. Invalid data provided | — | | 401 | No valid authentication details were provided | — | | 404 | Data cannot be found | — | | 500 | System Error | — | ### 200 response schema All response properties are optional in the schema. | Property | Type | Required | Description | |----------|------|----------|-------------| | `message_id` | string | No | | | `long_url` | string | No | | | `short_url` | string | No | | | `destination_number` | string | No | | | `click_count` | number | No | | | `view_count` | number | No | | | `clicks` | array of `Click` | No | List of click events. | | `views` | array of `View` | No | List of view events. | | `pagination` | `Pagination` object | No | | #### `clicks` item schema (`Click`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `dt` | string | No | | | `user_agent` | string | No | | | `ip` | string | No | | #### `views` item schema (`View`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `dt` | string | No | | | `user_agent` | string | No | | | `ip` | string | No | | #### `pagination` schema (`Pagination`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `page` | number | No | The current page of results | | `page_size` | number | No | The amount of results returned per page | | `total_count` | number | No | The total number of results in the results set | | `page_count` | number | No | The total number of pages in the results set | | `next_uri` | string | No | Link to the next page of results | | `previous_uri` | string | No | Link to the previous page of results | ### Example 200 response ```json { "message_id": "00000000-0000-0000-0000-000000000000", "long_url": "https://developers.sinch.com", "short_url": "https://nxt.to/abc1234", "destination_number": "+61491570157", "click_count": 3, "view_count": 2, "clicks": [ { "dt": "2018-09-18T01:22:17.071493", "user_agent": "Mozilla/5.0 (Windows NT...", "ip": "127.0.0.1" } ], "views": [ { "dt": "2018-09-18T01:22:17.071493", "user_agent": "Mozilla/5.0 (Windows NT...", "ip": "127.0.0.1" } ], "pagination": { "page": 1, "page_size": 100, "page_count": 3 } } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/reporting/links/detail?hash=abc1234&page=1&pageSize=20" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const url = new URL("https://eu.app.api.sinch.com/v1/reporting/links/detail"); url.search = new URLSearchParams({ hash: "abc1234", page: "1", pageSize: "20" }); const response = await fetch(url, { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Bad Request. Invalid data provided. Check the supplied query parameter values. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Data cannot be found. No detail report matches the supplied `hash`. - **500 Internal Server Error**: System Error. ## Related endpoints - [Log summary](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-summary.md) [← Short Trackable Links Reports](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/index.md) --- ### Source: docs/api/short-trackable-links-reports/log-summary.md # Log summary Retrieve aggregate click and view counts for short trackable URLs, optionally filtered by metadata, URL, or recipient. Clicks summary report for metadata key value pair, long url and short url. | | | |---|---| | **Service** | [Short Trackable Links Reports](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/reporting/links/summary` | | **Operation ID** | `LogSummary` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | None (all query parameters are optional) | ### Minimal request ```text GET /v1/reporting/links/summary ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `key` | string | No | Metadata key used to filter results. | | `value` | string | No | Metadata value used to filter results. | | `url` | string | No | URL used to filter results. | | `recipient` | string | No | Recipient address used to filter results. | | `page` | number (double) | No | Page number for pagination (1-based). | | `pageSize` | number (double) | No | Number of results per page. | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `LogSummaryResult` | | 400 | Bad Request. Invalid data provided | — | | 401 | No valid authentication details were provided | — | | 404 | Data cannot be found | — | | 500 | System Error | — | ### 200 response schema All response properties are optional in the schema. | Property | Type | Required | Description | |----------|------|----------|-------------| | `total_clicks` | number | No | | | `unique_clicks` | number | No | | | `total_views` | number | No | | | `unique_views` | number | No | | | `short_urls_generated` | number | No | | | `short_urls` | array of `ShortUrl` | No | List of short URLs. | | `pagination` | `Pagination` object | No | | #### `short_urls` item schema (`ShortUrl`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `click_count` | number | No | | | `view_count` | number | No | | | `message_id` | string | No | | | `long_url` | string | No | | | `short_url` | string | No | | | `destination_number` | string | No | | #### `pagination` schema (`Pagination`) | Property | Type | Required | Description | |----------|------|----------|-------------| | `page` | number | No | The current page of results | | `page_size` | number | No | The amount of results returned per page | | `total_count` | number | No | The total number of results in the results set | | `page_count` | number | No | The total number of pages in the results set | | `next_uri` | string | No | Link to the next page of results | | `previous_uri` | string | No | Link to the previous page of results | ### Example 200 response ```json { "total_clicks": 3, "unique_clicks": 1, "total_views": 2, "unique_views": 1, "short_urls_generated": 1, "short_urls": [ { "click_count": 3, "view_count": 2, "message_id": "00000000-0000-0000-0000-000000000000", "long_url": "https://developers.sinch.com", "short_url": "https://nxt.to/abc1234", "destination_number": "+61491570157" } ], "pagination": { "page": 1, "page_size": 100, "page_count": 3 } } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/reporting/links/summary?key=campaign&value=example&url=https%3A%2F%2Fdevelopers.sinch.com&recipient=%2B61491570157&page=1&pageSize=20" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const url = new URL("https://eu.app.api.sinch.com/v1/reporting/links/summary"); url.search = new URLSearchParams({ key: "campaign", value: "example", url: "https://developers.sinch.com", recipient: "+61491570157", page: "1", pageSize: "20" }); const response = await fetch(url, { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400 Bad Request**: Bad Request. Invalid data provided. Check the supplied query parameter values. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Data cannot be found. - **500 Internal Server Error**: System Error. ## Related endpoints - [Log detail](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/log-detail.md) [← Short Trackable Links Reports](https://developers.app.sinch.com/docs/api/short-trackable-links-reports/index.md) --- ### Source: docs/api/signature-key-management/create-signature-key.md # Create signature key Create a public/private key pair for signing and verifying webhook requests. Store the returned public key, then enable the key before use. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys` | | **Operation ID** | `CreateSignatureKey` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — The new signature key has been created. | | **Required** | `Accept` header; JSON request body | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `digest` | string | Yes | | | `cipher` | string | Yes | | ### Example request body ```json { "digest": "SHA224", "cipher": "RSA" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | The new signature key has been created. | `Createsignaturekeyresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `Enablesignaturekey400response` | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 201 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | Yes | | | `public_key` | string | Yes | | | `cipher` | string | Yes | | | `digest` | string | Yes | | | `created` | string | Yes | | | `enabled` | boolean | Yes | | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/iam/signature_keys" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"digest":"SHA224","cipher":"RSA"}' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/iam/signature_keys", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ digest: "SHA224", cipher: "RSA" }) }); const key = await response.json(); console.log(key); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. The `details` array contains additional error detail messages. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) - [Get signature key detail](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-detail.md) - [Delete signature key](https://developers.app.sinch.com/docs/api/signature-key-management/delete-signature-key.md) ## Specification details This will create a key pair: - The `private key` stored in Sinch is used to create the signature. - The `public key` is returned and stored at your side to verify the signature in webhooks. You need to enable your signature key after creating. The most basic body has the following structure: ```javascript { "digest": "SHA224", "cipher": "RSA" } ``` - `digest` is used to hash the message. The valid values for digest type are: SHA224, SHA256, SHA512 - `cipher` is used to encrypt the hashed message. The valid value for cipher type is: RSA A successful request for the `create signature key` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "public_key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCTIxtRyT5CuOD74r7UCT+AKzWNxvaAP9myjAqR7+vBnJKEvoPnmbKTnm6uLlxutnMbjKrnCCWnQ9vtBVnnd+ElhwLDPADfMcJoOqwi7mTcxucckeEbBsfsgYRfdacxgSZL8hVD1hLViQr3xwjEIkJcx1w3x8npvwMuTY0uW8+PjwIDAQAB", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ``` The response body of a successful POST request to the `create signature key` endpoint will contain six properties: - `key_id` will be a 36 character UUID which can be used to enable, delete or get the details. - `public_key` is used to decrypt the signature. - `cipher` same as cipher in request body. - `digest` same as digest in request body. - `created` is the created date. - `enabled` is false for the new signature key. You can use the `enable signature key` endpoint to set this field to true. [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/delete-signature-key.md # Delete signature key Delete one signature key by its `key_id`. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys/{key_id}` | | **Operation ID** | `DeleteSignatureKey` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The signature key has been deleted. | | **Required** | Path parameter `key_id` | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `key_id` | string | Yes | Unique identifier of the signature key. | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The signature key has been deleted. | — | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 403 and 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/iam/signature_keys/7ca628a8-08b0-4e42-aeb8-960b37049c31" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const keyId = "7ca628a8-08b0-4e42-aeb8-960b37049c31"; const response = await fetch( `https://eu.app.api.sinch.com/v1/iam/signature_keys/${keyId}`, { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } } ); console.log(response.status); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No entity matches the supplied `key_id`. ## Related endpoints - [Get signature key detail](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-detail.md) - [Get signature key list](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-list.md) - [Disable the current enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/disable-the-current-enabled-signature-key.md) ## Specification details Delete a signature key using the key_id returned in the `create signature key` endpoint. A successful request for the `delete signature key` endpoint will return an empty response body. *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/disable-the-current-enabled-signature-key.md # Disable the current enabled signature key Disable the currently enabled signature key. The operation also succeeds when no key is enabled. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled` | | **Operation ID** | `DisableTheCurrentEnabledSignatureKey` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `204` — No content. | | **Required** | None (no path, query, header, or body parameters) | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | No content. | — | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch( "https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } } ); console.log(response.status); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Get enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/get-enabled-signature-key.md) - [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) - [Delete signature key](https://developers.app.sinch.com/docs/api/signature-key-management/delete-signature-key.md) ## Specification details Disable the current enabled signature key. A successful request for the `disable the current enabled signature key` endpoint will return no content when successful. If there is an enabled key, it will be disabled; and the 204 status code is returned. If there is no key or no enabled key, the 204 status code is also returned. [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/enable-signature-key.md # Enable signature key Enable a signature key. Enabling a new key disables the previously enabled key. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled` | | **Operation ID** | `EnableSignatureKey` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The enabled signature key. | | **Required** | `Accept` header; JSON request body | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Accept` | string | Yes | Requested response media type. | ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | Yes | | ### Example request body ```json { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The enabled signature key. | `Enablesignaturekeyresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `Enablesignaturekey400response` | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | No | | | `cipher` | string | No | | | `digest` | string | No | | | `created` | string | No | | | `enabled` | boolean | No | | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### 403 and 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"key_id":"7ca628a8-08b0-4e42-aeb8-960b37049c31"}' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ key_id: "7ca628a8-08b0-4e42-aeb8-960b37049c31" }) }); const key = await response.json(); console.log(key); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. The `details` array contains additional error detail messages. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No entity matches the supplied `key_id`. ## Related endpoints - [Create signature key](https://developers.app.sinch.com/docs/api/signature-key-management/create-signature-key.md) - [Get enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/get-enabled-signature-key.md) - [Disable the current enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/disable-the-current-enabled-signature-key.md) ## Specification details Enable a signature key using the key_id returned in the `create signature key` endpoint. There is only one signature key is enabled at the one moment in time. So if you enable the new signature key, the old one will be disabled. The most basic body has the following structure: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31" } ``` The response body of a successful PATCH request to `enable signature key` endpoint will contain the `enabled` properties with the value is true as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": true } ``` *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/get-enabled-signature-key.md # Get enabled signature key Retrieve the signature key that is currently enabled. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled` | | **Operation ID** | `GetEnabledSignatureKey` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The detail of signature key. | | **Required** | None (no path, query, header, or body parameters) | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The detail of signature key. | `Getenabledsignaturekeyresponse` | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | No | | | `cipher` | string | No | | | `digest` | string | No | | | `created` | string | No | | | `enabled` | boolean | No | | ### 403 and 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch( "https://eu.app.api.sinch.com/v1/iam/signature_keys/enabled", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } } ); const key = await response.json(); console.log(key); ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. The operation notes that this is returned when no signature key is enabled. ## Related endpoints - [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) - [Disable the current enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/disable-the-current-enabled-signature-key.md) - [Get signature key list](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-list.md) ## Specification details Retrieve the currently enabled signature key. A successful request for the `get enabled signature key` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": true } ``` *Note: If there is no enabled signature key, then an HTTP 404 Not Found response will be returned* [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/get-signature-key-detail.md # Get signature key detail Retrieve one signature key by its `key_id`. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys/{key_id}` | | **Operation ID** | `GetSignatureKeyDetail` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The detail of signature key. | | **Required** | Path parameter `key_id` | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `key_id` | string | Yes | Unique identifier of the signature key. | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The detail of signature key. | `Getsignaturekeydetailresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `Enablesignaturekey400response` | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | | 404 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 200 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | No | | | `cipher` | string | No | | | `digest` | string | No | | | `created` | string | No | | | `enabled` | boolean | No | | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### 403 and 404 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/iam/signature_keys/7ca628a8-08b0-4e42-aeb8-960b37049c31" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const keyId = "7ca628a8-08b0-4e42-aeb8-960b37049c31"; const response = await fetch( `https://eu.app.api.sinch.com/v1/iam/signature_keys/${keyId}`, { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } } ); const key = await response.json(); console.log(key); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. - **404 Not Found**: Unexpected error in API call. See HTTP response body for details. No entity matches the supplied `key_id`. ## Related endpoints - [Get signature key list](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-list.md) - [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) - [Delete signature key](https://developers.app.sinch.com/docs/api/signature-key-management/delete-signature-key.md) ## Specification details Retrieve the current detail of a signature key using the key_id returned in the `create signature key` endpoint. A successful request for the `get signature key detail` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ``` *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/get-signature-key-list.md # Get signature key list Retrieve a page of signature keys for the authenticated account. | | | |---|---| | **Service** | [Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/iam/signature_keys` | | **Operation ID** | `GetSignatureKeyList` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — The list of signature keys. | | **Required** | Query parameters `page` and `page_size` | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | string | Yes | Page number for pagination (1-based). | | `page_size` | string | Yes | Number of results per page. | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | The list of signature keys. | array of `Getsignaturekeylistresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `Enablesignaturekey400response` | | 401 | No valid authentication details were provided | — | | 403 | Unexpected error in API call. See HTTP response body for details. | `Disablethecurrentenabledsignaturekey.403response` | ### 200 response schema The response is an array whose items have this schema: | Property | Type | Required | Description | |----------|------|----------|-------------| | `key_id` | string | No | | | `cipher` | string | No | | | `digest` | string | No | | | `created` | string | No | | | `enabled` | boolean | No | | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | Yes | Additional error detail messages. | ### 403 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/iam/signature_keys?page=1&page_size=20" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch( "https://eu.app.api.sinch.com/v1/iam/signature_keys?page=1&page_size=20", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } } ); const keys = await response.json(); console.log(keys); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. The `details` array contains additional error detail messages. - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials. - **403 Forbidden**: Unexpected error in API call. See HTTP response body for details. ## Related endpoints - [Create signature key](https://developers.app.sinch.com/docs/api/signature-key-management/create-signature-key.md) - [Get signature key detail](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-detail.md) - [Get enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/get-enabled-signature-key.md) ## Specification details Retrieve the paginated list of signature keys. A successful request for the `get signature key list` endpoint will return a response body as follows: ```javascript [ { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ] ``` [← Signature Key Management](https://developers.app.sinch.com/docs/api/signature-key-management/index.md) --- ### Source: docs/api/signature-key-management/index.md # Signature Key Management Manage the keys Sinch uses to sign webhook requests so your application can verify that each request came from Sinch. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Create a key pair | [Create signature key](https://developers.app.sinch.com/docs/api/signature-key-management/create-signature-key.md) | | List all signature keys | [Get signature key list](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-list.md) | | Inspect one key | [Get signature key detail](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-detail.md) | | Delete one key | [Delete signature key](https://developers.app.sinch.com/docs/api/signature-key-management/delete-signature-key.md) | | Make a key active | [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) | | Retrieve the active key | [Get enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/get-enabled-signature-key.md) | | Disable the active key | [Disable the current enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/disable-the-current-enabled-signature-key.md) | Create a key, store its returned public key, and then enable it. Only one signature key can be enabled at a time. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Get signature key list](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-list.md) | `GET` | `/v1/iam/signature_keys` | Get signature key list | | [Create signature key](https://developers.app.sinch.com/docs/api/signature-key-management/create-signature-key.md) | `POST` | `/v1/iam/signature_keys` | Create signature key | | [Get signature key detail](https://developers.app.sinch.com/docs/api/signature-key-management/get-signature-key-detail.md) | `GET` | `/v1/iam/signature_keys/{key_id}` | Get signature key detail | | [Delete signature key](https://developers.app.sinch.com/docs/api/signature-key-management/delete-signature-key.md) | `DELETE` | `/v1/iam/signature_keys/{key_id}` | Delete signature key | | [Enable signature key](https://developers.app.sinch.com/docs/api/signature-key-management/enable-signature-key.md) | `PATCH` | `/v1/iam/signature_keys/enabled` | Enable signature key | | [Get enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/get-enabled-signature-key.md) | `GET` | `/v1/iam/signature_keys/enabled` | Get enabled signature key | | [Disable the current enabled signature key](https://developers.app.sinch.com/docs/api/signature-key-management/disable-the-current-enabled-signature-key.md) | `DELETE` | `/v1/iam/signature_keys/enabled` | Disable the current enabled signature key | ## Specification details As a Sinch customer, you want to be able to ensure that webhooks are coming from Sinch and not from a 3rd party. Since these are calls to your own system, you should be provided with an extra level of security when calling your resources. The Sinch Signature Key API provides a number of endpoints for managing key used to sign each unique request to ensure security and the requests can't (easily) be spoofed. This is similar to using HMAC in your outbound messaging (rather than HTTP Basic). The Signature Key API provides seven main endpoints: - `Create signature key` Create a new signature key for signature verification in webhooks. - `Get signature key detail` Retrieve the current detail of a signature key using the key_id returned in the `create signature key` endpoint. - `Delete signature key` Delete a signature key using the key_id returned in the `create signature key` endpoint. - `Get signature key list` Retrieve the paginated list of signature keys. - `Enable signature key` Enable a signature key using the key_id returned in the `create signature key` endpoint. - `Get enabled signature key` Retrieve the current enabled signature key. - `Disable an enabled signature key` Disable the current enabled signature key. [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/source-address/delete-sender-address-using-delete.md # Delete Sender Address Remove an approved sender address from the account. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/{id}` | | **Operation ID** | `deleteSenderAddressUsingDELETE` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `202` — Accepted | | **Required** | `id`, `reason` | ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string (uuid) | Yes | Sender address UUID (from GET .../addresses), not the request UUID | | ### Query parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `reason` | string | Yes | A string detailing why the sender address is being removed | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 202 | Accepted | None | | 400 | Bad Request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | | 404 | Resource not found | `404response` | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/?reason=I%20want%20do%20delete%20this%20number." \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/?reason=I%20want%20do%20delete%20this%20number.", { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); console.log(response.status); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized - **403**: Forbidden - **404**: Resource not found ## Related endpoints - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) - [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) - [Request a Sender Address](https://developers.app.sinch.com/docs/api/source-address/request-sender-address-using-post.md) ## Specification details Remove an approved sender address from your account. The path `id` must be the **sender address** UUID from **Get all approved sender addresses**. Using the **request** UUID from **Request a Sender Address** will return `404 Not found`. [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/get-all-approved-sender-addresses.md # Get all approved sender addresses List approved sender addresses, optionally filtering and paginating the results. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses` | | **Operation ID** | `GetAllApprovedSenderAddresses` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — A list of approved sender addresses for your account only | | **Required** | None | ### Example success body ```json { "data": [ { "id": "7927d9eb-4e74-4021-836e-6cae071f84e7", "sender_address": "EXAMPLE1", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my reason 1", "label": "This is my label 1", "account_id": "my_account", "created_date": "2023-08-04T04:21:55.958Z", "last_modified_date": "2023-08-04T04:21:55.958Z" }, { "id": "365dd65f-7101-46cd-8e79-e49c5620eb15", "sender_address": "EXAMPLE2", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my reason 2", "label": "This is my label 2", "account_id": "my_account", "created_date": "2023-08-14T04:21:55.958Z", "last_modified_date": "2023-08-14T04:21:55.958Z" }, { "id": "4a9cb0f4-f383-40b5-84dc-bbb6a3b210dd", "sender_address": "61491570156", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "This is my reason 3", "label": "This is my label 3", "account_id": "my_account", "created_date": "2023-08-24T04:21:55.958Z", "last_modified_date": "2023-08-24T04:21:55.958Z", "expiry": "2024-08-03T04:21:55.958Z", "display_status": "APPROVED" } ], "pagination": { "page_size": 20, "next_token": "UWFTeXNBZGRyMSN8JEAsdmVuZG9ySWRUZXN0MSN8JEAsYWNjb3VudElkVGVzdDI=" } } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `sender_address` | string | No | A string containing some or all of a specific Sender ID | | | `sender_address_type` | string | No | The type of Sender ID. This will be either ALPHANUMERIC, INTERNATIONAL, or SHORT_CODE | Enum: `ALPHANUMERIC`, `INTERNATIONAL`, `SHORT_CODE` | | `usage_type` | string | No | The usage type of the Sender ID | Enum: `ALPHANUMERIC`, `OWN_NUMBER`, `DEDICATED`, `HOSTED_NUMBER` | | `include_related_accounts` | boolean | No | When true, include Sender IDs that belong to related accounts in addition to those on the authenticated account.
| | | `expiry_status` | string | No | Filter the results by OWN_NUMBER Sender IDs that are already expired, or will expire soon.
Acceptable values are EXPIRED and EXPIRING. This parameter requires both the sender_address_type and usage_type parameters to be present.
| Enum: `EXPIRED`, `EXPIRING` | | `page_size` | integer | No | The number of results per page. Default is 20. | Default: `20` | | `token` | string | No | In paginated data, the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. | | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A list of approved sender addresses for your account only | `GetAllApprovedSenderAddresses` | | 400 | Bad request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | ### 200 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `data` | array of object | No | | | | `pagination` | object | No | | | #### `data[]` schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Approved sender address UUID (use for get, update, re-verify, and delete) | | | `sender_address` | string | No | The sender address value (alpha tag or phone number as a string) | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `ALPHANUMERIC`, `INTERNATIONAL`, `SHORT_CODE` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `ALPHANUMERIC`, `OWN_NUMBER`, `DEDICATED`, `HOSTED_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `account_id` | string | No | Account that owns this sender address | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | | `expiry` | string (date-time) | No | The Sender Address expiration time (apply for sender_address_type = OWN_NUMBER)
| | | `display_status` | string | No | The Sender Address status (apply for sender_address_type = OWN_NUMBER)
| Enum: `APPROVED`, `EXPIRING`, `EXPIRED` | #### `pagination` schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `page_size` | number | No | | | | `next_token` | string | No | The pagination token of the next set of results. | | ### Example 200 response ```json { "data": [ { "id": "7927d9eb-4e74-4021-836e-6cae071f84e7", "sender_address": "EXAMPLE1", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my reason 1", "label": "This is my label 1", "account_id": "my_account", "created_date": "2023-08-04T04:21:55.958Z", "last_modified_date": "2023-08-04T04:21:55.958Z" }, { "id": "365dd65f-7101-46cd-8e79-e49c5620eb15", "sender_address": "EXAMPLE2", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my reason 2", "label": "This is my label 2", "account_id": "my_account", "created_date": "2023-08-14T04:21:55.958Z", "last_modified_date": "2023-08-14T04:21:55.958Z" }, { "id": "4a9cb0f4-f383-40b5-84dc-bbb6a3b210dd", "sender_address": "61491570156", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "This is my reason 3", "label": "This is my label 3", "account_id": "my_account", "created_date": "2023-08-24T04:21:55.958Z", "last_modified_date": "2023-08-24T04:21:55.958Z", "expiry": "2024-08-03T04:21:55.958Z", "display_status": "APPROVED" } ], "pagination": { "page_size": 20, "next_token": "UWFTeXNBZGRyMSN8JEAsdmVuZG9ySWRUZXN0MSN8JEAsYWNjb3VudElkVGVzdDI=" } } ``` ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses?sender_address=EXAMPLE&sender_address_type=ALPHANUMERIC&usage_type=ALPHANUMERIC&include_related_accounts=true&expiry_status=EXPIRED&page_size=20&token=eyJwYWdlIjoyfQ" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses?sender_address=EXAMPLE&sender_address_type=ALPHANUMERIC&usage_type=ALPHANUMERIC&include_related_accounts=true&expiry_status=EXPIRED&page_size=20&token=eyJwYWdlIjoyfQ", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad request - **401**: Unauthorized - **403**: Forbidden ## Related endpoints - [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) - [Update My Own Number Label](https://developers.app.sinch.com/docs/api/source-address/update-sender-address-using-patch.md) - [Re-verify Sender Address](https://developers.app.sinch.com/docs/api/source-address/re-verify-sender-address-using-post.md) - [Delete Sender Address](https://developers.app.sinch.com/docs/api/source-address/delete-sender-address-using-delete.md) - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) ## Specification details Retrieve all **approved sender addresses** currently registered to your account. Each item's `id` is the **sender address** UUID. Use this UUID to get, update, re-verify, or delete a sender. It is different from the request UUID returned when you created the sender. [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/get-sender-address-by-id.md # Get sender address by id Retrieve one approved sender address using its sender address UUID. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/{id}` | | **Operation ID** | `GetSenderAddressById` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — A sender address for your account only | | **Required** | `id` | ### Example success body ```json { "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b8", "sender_address": "+61401234567", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "my personal number", "label": "ABC", "account_id": "XYZ_ExampleAccount", "created_date": "", "last_modified_date": "", "expiry": "", "display_status": "APPROVED" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string (uuid) | Yes | Sender address UUID (from GET .../addresses), not the request UUID | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | A sender address for your account only | `GetSenderAddress` | | 400 | Bad request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | ### 200 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Approved sender address UUID (use for get, update, re-verify, and delete) | | | `sender_address` | string | No | The sender address value (alpha tag or phone number as a string) | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `ALPHANUMERIC`, `INTERNATIONAL`, `SHORT_CODE` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `ALPHANUMERIC`, `OWN_NUMBER`, `DEDICATED`, `HOSTED_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | | `expiry` | string (date-time) | No | The Sender Address expiration time (apply for sender_address_type = OWN_NUMBER) | | | `display_status` | string | No | | Enum: `APPROVED`, `EXPIRED`, `EXPIRING` | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad request - **401**: Unauthorized - **403**: Forbidden ## Related endpoints - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) - [Update My Own Number Label](https://developers.app.sinch.com/docs/api/source-address/update-sender-address-using-patch.md) - [Re-verify Sender Address](https://developers.app.sinch.com/docs/api/source-address/re-verify-sender-address-using-post.md) - [Delete Sender Address](https://developers.app.sinch.com/docs/api/source-address/delete-sender-address-using-delete.md) - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) ## Specification details Retrieve an approved sender address by its **sender address** UUID (from **Get all approved sender addresses**). Do not use the request UUID returned by **Request a Sender Address**. [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/get-status-of-sender-address-request.md # Get status of a sender address request Retrieve the current state of a sender address registration request. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests/{id}` | | **Operation ID** | `GetStatusOfSenderAddressRequest` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — Get the status of Sender Address Request | | **Required** | `id` | ### Example success body ```json { "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b7", "sender_address": "EXAMPLE", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my reason", "label": "label", "status": "OPEN", "account_id": "XYZ_ExampleAccount", "created_date": "", "last_modified_date": "" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | 36 character UUID. | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Get the status of Sender Address Request | `AlphaTagRequestItem` | | 400 | Bad request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Primary ID of the record | | | `sender_address` | string | No | The Alpha tag to be requested | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `ALPHANUMERIC` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `ALPHANUMERIC` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `status` | string | No | | Enum: `OPEN`, `PENDING`, `REJECTED`, `APPROVED` | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests/" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests/", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad request - **401**: Unauthorized - **403**: Forbidden - **404**: Resource not found ## Related endpoints - [Request a Sender Address](https://developers.app.sinch.com/docs/api/source-address/request-sender-address-using-post.md) - [Submitting a verification code](https://developers.app.sinch.com/docs/api/source-address/submitting-verification-code-post.md) - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) ## Specification details Retrieve the current status of a sender address request using the request ID returned in the sender address request endpoint. A successful request to the get message status endpoint will return a response body as follows: ```json { "id": "365dd65f-7101-46cd-8e79-e49c5620eb15", "sender_address": "sample", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my approval reason", "label": "label" "status": "APPROVED", "account_id": "sample", "created_date": "2023-09-07T05:48:26.741Z", "last_modified_date": "2023-09-07T05:49:20.888Z" } ``` [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/index.md # Source Address The Source Address API lets you request SMS sender IDs and track their approval status. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Choose an endpoint | Goal | Endpoint | |------|----------| | Register an alpha tag or personal number | [Request a Sender Address](https://developers.app.sinch.com/docs/api/source-address/request-sender-address-using-post.md) | | Submit the SMS code for a personal number | [Submitting a verification code](https://developers.app.sinch.com/docs/api/source-address/submitting-verification-code-post.md) | | Check a registration request | [Get status of a sender address request](https://developers.app.sinch.com/docs/api/source-address/get-status-of-sender-address-request.md) | | List approved sender addresses and obtain address UUIDs | [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) | | Retrieve, relabel, reverify, or remove an approved sender | [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) | Request UUIDs identify applications; approved sender address UUIDs identify senders. Use [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) after approval to obtain the UUID required by address-management endpoints. ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Request a Sender Address](https://developers.app.sinch.com/docs/api/source-address/request-sender-address-using-post.md) | `POST` | `/v1/messaging/numbers/sender_address/requests` | Request a Sender Address | | [Submitting a verification code](https://developers.app.sinch.com/docs/api/source-address/submitting-verification-code-post.md) | `POST` | `/v1/messaging/numbers/sender_address/requests/{id}/verify` | Submitting a verification code | | [Re-verify Sender Address](https://developers.app.sinch.com/docs/api/source-address/re-verify-sender-address-using-post.md) | `POST` | `/v1/messaging/numbers/sender_address/addresses/{id}/reverify` | Re-verify Sender Address | | [Get status of a sender address request](https://developers.app.sinch.com/docs/api/source-address/get-status-of-sender-address-request.md) | `GET` | `/v1/messaging/numbers/sender_address/requests/{id}` | Get status of a sender address request | | [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) | `GET` | `/v1/messaging/numbers/sender_address/addresses` | Get all approved sender addresses | | [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) | `GET` | `/v1/messaging/numbers/sender_address/addresses/{id}` | Get sender address by id | | [Update My Own Number Label](https://developers.app.sinch.com/docs/api/source-address/update-sender-address-using-patch.md) | `PATCH` | `/v1/messaging/numbers/sender_address/addresses/{id}` | Update My Own Number Label | | [Delete Sender Address](https://developers.app.sinch.com/docs/api/source-address/delete-sender-address-using-delete.md) | `DELETE` | `/v1/messaging/numbers/sender_address/addresses/{id}` | Delete Sender Address | ## Specification details The source address API provides several endpoints for you to request an SMS sender ID and track its approval status. ### Sender address request vs sender address This API uses two different resources, each with its own UUID: | | Sender address **request** | Approved sender **address** | |---|----------------------------|-----------------------------| | What it is | Your registration / verification application | The approved sender ID on your account | | Path | `/v1/messaging/numbers/sender_address/requests` | `/v1/messaging/numbers/sender_address/addresses` | | `id` returned by | **Request a Sender Address** (`POST .../requests`) | **Get all approved sender addresses** (`GET .../addresses`) | | Use that `id` for | Get request status, submit a verification code | Get, update, re-verify, or **delete** the sender | The request `id` and the address `id` are **not the same**. After a sender is approved, call **Get all approved sender addresses** to obtain the address `id` before deleting or managing it. Using the request `id` on address endpoints (for example delete) returns `404 Not found`. **What is Trusted Sender ID?** Simply put, a sender ID is whatever you send a text message from. This is typically either a phone number, or a string of alphanumeric characters (commonly referred to as an "Alpha Tag"). With regulations surrounding SMS becoming much stricter all over the world in an effect to combat scam SMS messages, Sinch is working on "Trusted Sender ID" a concept that allows customers to request a Sender ID and have it verified. Currently, Trusted Sender ID supports two types of Sender ID: Alpha Tags and Personal ("Own") Numbers. It will likely be extended to support additional number types, such as TFN and 10DLC where additional registration, (external) verification, and overall account allowlist of numbers will be required. ### Alpha Tag Sending messages from your brand name is particularly ideal for SMS marketing and two-factor authentication, as it increases recognition and trust. There are, however, a few considerations to be aware of. Alpha tags are made up of 3-11 letters and/or numbers. Alpha tags must be registered and approved before sending and must have clear relevancy to your business and/or use case. Alpha Tags appear as the "From" number when you receive messages. A good alpha tag meets at least one of the following valid use cases: * Business names * Trademark names * Product or service name * an acronym, initialism, or contraction of your entity In addition to the requirements around clearly relating to the business, we typically advise the following for alpha tags to ensure maximum compatibility with the various carriers: * 6-11 characters long * Only contains characters from the following sets: * A-Z * a-z * 0-9 * _ (underscore) * \- (hyphen) Alpha Tags can currently be registered through the Source Address API for the following countries: ```AD```, ```AI```, ```AL```, ```AS```, ```AT```, ```AU```, ```AW```, ```BA```, ```BB```, ```BH```, ```BW```, ```CD```, ```CH```, ```CK```, ```CY```, ```DE```, ```DJ```, ```DK```, ```DM```, ```EE```, ```ES```, ```FI```, ```FJ```, ```FM```, ```FO```, ```FR```, ```GB```, ```GD```, ```GG```, ```GI```, ```GL```, ```GM```, ```GQ```, ```GR```, ```GY```, ```IL```, ```IM```, ```IS```, ```JE```, ```JM```, ```JP```, ```KI```, ```KY```, ```LA```, ```LI```, ```LS```, ```LT```, ```LU```, ```LV```, ```MC```, ```ME```, ```MH```, ```MO```, ```MR```, ```MS```, ```MT```, ```MV```, ```NC```, ```NF```, ```NL```, ```NO```, ```NR```, ```NU```, ```PF```, ```PM```, ```PT```, ```SB```, ```SC```, ```SE```, ```SH```, ```SL```, ```SM```, ```ST```, ```TC```, ```TD```, ```TO```, ```VC```, ```VG``` and ```WS``` To register an Alpha Tag as a sender ID you must: 1. Make a request to the **Request a Sender Address** endpoint 2. Wait for the alpha tag to be approved. The status of the alpha tag can be monitored using the **Get status of a sender address request** endpoint Once the alpha tag has been approved, you can begin using it as a Sender ID for SMS messages. ### Personal Number A personal number, or "My Own Number", is a number that you own rather than one provided to you by Sinch. Typically, this is your personal mobile phone number. You may wish to register this number for use with our service so that you can easily send messages from a number already associated with your organisation. Before you can send messages using your own number, you need to verify that you have a right to use that number. Ensuring you have a right to use a phone number is an important regulatory requirement, aiming to prevent scam, spam, and misuse of messaging services. Personal numbers can currently be registered through the Source Address API for the following countries: ```AT```, ```AU```, ```CH```, ```CY```, ```DE```, ```DK```, ```EE```, ```ES```, ```FI```, ```GB```, ```HR```, ```IE```, ```IT```, ```LT```, ```LU```, ```LV```, ```MT```, ```NL```, ```NO```, ```PT```, ```SE```, and ```SI``` To register a personal number as a Sender ID you must: 1. Make a request to the **Request a Sender Address** endpoint (store the **request** UUID for verification) 2. A unique verification code will be sent to the requested number 3. Make a request to the **Submitting a Verification Code** endpoint, using the verification code that was sent in the previous step. A 200 OK response will indicate the number has been verified and is ready for use. 4. To delete or manage the sender later, call **Get all approved sender addresses** and use the **address** UUID from that response (different from the request UUID in step 1). ⚠️ Own numbers need to be re-verified every 12 months. You will be notified by email that verification of your number is about to expire. ### Requesting a Source Address on behalf of a sub-account By default, all requests made through the API are made on behalf of the account that the API keys used to authorize the request were made on. API keys created on a parent account can request a source address on behalf of a sub-account. To do this, include a header key ```Account``` with the sub-account ID as the value. For example: ```Account: mySubAccount``` **Example request with Request a Sender Address from a sub-account** ```plain POST /v1/messaging/numbers/sender_address/requests HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp Account: mySubAccount { "sender_address": "+61341234131", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "I confirm that my business has a valid use case", "label": "my number sample" } ``` *Note: The use of the Account header key applies to all Source Address endpoints.* [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/source-address/re-verify-sender-address-using-post.md # Re-verify Sender Address Start the annual 2FA reverification process for an approved own-number sender address. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/{id}/reverify` | | **Operation ID** | `reVerifySenderAddressUsingPOST` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | `id` | ### Example success body ```json { "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b7", "sender_address": "+61450999999", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU", "NZ", "US" ], "reason": "my company is example.com", "label": "Example Address", "status": "PENDING", "account_id": "XYZ_ExampleAccount", "created_date": "", "last_modified_date": "" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | Sender Address ID | | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `ReVerifySenderAddressRequestItem` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Primary ID of the record | | | `sender_address` | string | No | The Sender Address to be requested | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `INTERNATIONAL` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `OWN_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `status` | string | No | | Enum: `PENDING` | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses//reverify" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses//reverify", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized - **403**: Forbidden - **404**: Resource not found ## Related endpoints - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) - [Submitting a verification code](https://developers.app.sinch.com/docs/api/source-address/submitting-verification-code-post.md) - [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) ## Specification details The below table defines the allowed combination of `sender_address_type` and `usage_type` values | Description | sender_address_type | usage_type | | ---------------- | ------------------- | ------------ | | Own Number | INTERNATIONAL | OWN_NUMBER | OWN_NUMBER Sender Addresses require reverification every 12 months to allow continued use. The reverification process is quite similar to the original verification process for the Sender Address, and requires a fresh 2FA check. To reverify an OWN_NUMBER Sender Address: 1. Retrieve the UUID for the OWN_NUMBER using the **Get all approved sender addresses** endpoint 2. Make a request to this endpoint to trigger the 2FA check 3. Make a POST request to the **Submit verification code endpoint**, providing the new 2FA code in the body of the request [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/request-sender-address-using-post.md # Request a Sender Address Submit an alpha tag or personal number for registration as an SMS sender ID. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests` | | **Operation ID** | `requestSenderAddressUsingPOST` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Created | | **Required** | `sender_address`, `sender_address_type`, `usage_type`, `destination_countries`, `reason` | ### Minimal request ```json { "sender_address": "EXAMPLE", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@email.com\",\n \"australianGovernmentAgencyOrEntityName\":\"bla bla\",\n \"statement\":\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\"\n}\n", "label": "label" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true - **Description:** Request body. ### Variant 1: `RequestAlphaTag` | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `sender_address` | string | Yes | The Sender Address to be requested | | | `sender_address_type` | string | Yes | | Enum: `ALPHANUMERIC` | | `usage_type` | string | Yes | | Enum: `ALPHANUMERIC` | | `destination_countries` | array of string | Yes | list of 2-character ISO country codes | | | `reason` | string | Yes | | | | `label` | string | No | | | ### Variant 2: `RequestVerificationCode` | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `sender_address` | string | Yes | The Own Number to be verified | | | `sender_address_type` | string | Yes | | Enum: `INTERNATIONAL` | | `usage_type` | string | Yes | | Enum: `OWN_NUMBER` | | `destination_countries` | array of string | Yes | list of 2-character ISO country codes | | | `reason` | string | Yes | | | | `label` | string | No | | | ### Example for RequestAlphaTag ```json { "sender_address": "EXAMPLE", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@email.com\",\n \"australianGovernmentAgencyOrEntityName\":\"bla bla\",\n \"statement\":\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\"\n}\n", "label": "label" } ``` ### Example for RequestVerificationCode ```json { "sender_address": "+61401234567", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "my personal number", "label": "label" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Created | `AlphaTagRequestItem` or `VerificationCodeRequestItem` | | 400 | Bad Request | None | | 401 | Unauthorized | None | | 403 | Forbidden | None | | 409 | Conflict | None | ### 201 response schema — `AlphaTagRequestItem` | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Primary ID of the record | | | `sender_address` | string | No | The Alpha tag to be requested | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `ALPHANUMERIC` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `ALPHANUMERIC` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `status` | string | No | | Enum: `OPEN`, `PENDING`, `REJECTED`, `APPROVED` | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | ### 201 response schema — `VerificationCodeRequestItem` | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Primary ID of the record | | | `sender_address` | string | No | The Own Number to be requested | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `INTERNATIONAL` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `OWN_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `status` | string | No | | Enum: `PENDING`, `REJECTED`, `APPROVED` | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | ### Example 201 response 1 ```json { "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b7", "sender_address": "EXAMPLE", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@email.com\",\n \"australianGovernmentAgencyOrEntityName\":\"bla bla\",\n \"statement\":\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\"\n}\n", "label": "label", "status": "OPEN", "account_id": "XYZ_ExampleAccount", "created_date": "2023-10-25T14:15:22Z", "last_modified_date": "2023-10-25T14:15:22Z" } ``` ### Example 201 response 2 ```json { "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b8", "sender_address": "+61401234567", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "my personal number", "label": "label", "status": "PENDING", "account_id": "XYZ_ExampleAccount", "created_date": "2023-10-24T14:15:22Z", "last_modified_date": "2023-10-24T14:15:22Z" } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "sender_address": "EXAMPLE", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@email.com\",\n \"australianGovernmentAgencyOrEntityName\":\"bla bla\",\n \"statement\":\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\"\n}\n", "label": "label" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ sender_address: "EXAMPLE", sender_address_type: "ALPHANUMERIC", usage_type: "ALPHANUMERIC", destination_countries: [ "AU" ], reason: "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@email.com\",\n \"australianGovernmentAgencyOrEntityName\":\"bla bla\",\n \"statement\":\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\"\n}\n", label: "label" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized - **403**: Forbidden - **409**: Conflict ## Related endpoints - [Get status of a sender address request](https://developers.app.sinch.com/docs/api/source-address/get-status-of-sender-address-request.md) - [Submitting a verification code](https://developers.app.sinch.com/docs/api/source-address/submitting-verification-code-post.md) - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) - [Send messages](https://developers.app.sinch.com/docs/api/messages/send-messages.md) ## Specification details Submit a **sender address request** to register a new Sender ID. The `id` in the response is the **request** UUID. Use it only with request endpoints (get status, submit verification code). It is **not** the approved sender address UUID. After approval, use **Get all approved sender addresses** to get the address `id` needed to delete or manage the sender. When making a request to this endpoint, you will always need to specify ```sender_address_type``` and ```usage_type``` parameters. The following table shows the acceptable values and combinations for these parameters: | Sender ID | sender_address_type | usage_type | |--- |--- |--- | | Alpha tag | `ALPHANUMERIC` | `ALPHANUMERIC` | | Personal number | `INTERNATIONAL` | `OWN_NUMBER` | The other parameters required for your request will depend on the type of Sender ID you are registering. ### Sender ID is an Alpha Tag The following parameters are used when registering an alpha tag as a Sender ID: - ```sender_address:``` **(Required)**. The alphanumeric string that you wish register as an alpha tag. This parameter is case insensitive. If this alpha tag already exists on your account, you will receive a conflict error message. - ```destination_countries:``` **(Required)**. The countries that you wish to register the alpha tag for use in, in two-character ISO 3166 format. Currently AD, AI, AL, AS, AT, AW, BA, BB, BH, BW, CD, CH, CK, CY, DE, DJ, DK, DM, EE, ES, FI, FJ, FM, FO, FR, GB, GD, GG, GI, GL, GM, GQ, GR, GY, IL, IM, IS, JE, JM, JP, KI, KY, LA, LI, LS, LT, LU, LV, MC, ME, MH, MO, MR, MS, MT, MV, NC, NF, NL, NO, NR, NU, PF, PM, PT, SB, SC, SE, SH, SL, SM, ST, TC, TD, TO, VC, VG and WS are supported. - ```sender_address_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC - ```usage_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it. - ```reason:``` **(Required)**. This is a specifically formatted string made up of the following sub-items (all of which are required): - `useCase:` one of the following: - `SOLE_TRADER_NAME` - `COMPANY_NAME` - `PARTNERSHIP_NAME` - `REGISTERED_TRUST_NAME` - `CO_OPERATIVE_NAME` - `INDIGENOUS_CORPORATION_NAME` - `REGISTERED_ORGANISATION_NAME` - `PERSONAL_NAME` - `AUSTRALIAN_TRADEMARK` - `INTERNATIONAL_TRADEMARK` - `AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY` - `FOREIGN_GOVERNMENT_AGENCY_OR_ENTITY` - `PRODUCT_OR_SERVICE_NAME` - `ACRONYM_INITIALISM` - `CONTRACTION_OF_NAME` - `OTHER` - `description:` A description used if OTHER was selected as the use case. Limited to 200 characters. - `email:` The preferred contact email for our approval team when additional details are required. - `australianGovernmentAgencyOrEntityName:` The name of your organisation. - `abn:` Your organisation’s Australian Business Number - `statement:` A legal declaration - If applying for your own business: "We are authorized to use the Sender ID with a valid use case." - If applying on behalf of a third-party entity: "We are authorized to use the Sender ID on behalf of [full entity name of sender] with a valid use case." The reason parameter must contain all the above items. A well formatted reason looks like the following: - "reason": "{\n  \\"useCase\\":\\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\\",\n  \\"description\\":\\"bal bla\\",\n  \\"email\\":\\"example@email.com\\",\n  \\"australianGovernmentAgencyOrEntityName\\":\\"bla bla\\",\n  \\"statement\\":\\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\\"\n}\n" ### Sender ID is a Personal Number The following parameters are used when registering a personal mobile phone number as a Sender ID: - ```sender_address:``` **(Required)**. The phone number that you wish register as a personal number. This number must be in E.164. If this number is already registered to an account, you will receive a conflict error message. - ```destination_countries:``` **(Required)**. The country of the number that you wish to register, in two-character ISO 3166 format. Refer to the **Types of Sender ID** section for a list of currently supported countries. - ```sender_address_type:``` **(Required)**. For personal numbers this is always INTERNATIONAL - ```usage_type:``` **(Required)**. For personal numbers this is always OWN_NUMBER - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it. - ```Reason:``` **(Required)**. A string describing why you wish to register the number as a Sender ID. Limited to 200 characters. [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/submitting-verification-code-post.md # Submitting a verification code Complete personal-number registration by submitting the six-digit SMS verification code. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests/{id}/verify` | | **Operation ID** | `SubmittingVerificationCodePost` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `201` — Created | | **Required** | `id`, `verification_code` | ### Minimal request ```json { "verification_code": "123456" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string | Yes | 36 character UUID. | | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true - **Description:** Verification code to be verified ### Schema (`PostVerificationCode`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `verification_code` | string | Yes | Verify Sender Address Request | | ### Example request body ```json { "verification_code": "123456" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Created | `VerificationCodeRequestItem` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | | 404 | Resource not found | `404response` | ### 201 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Primary ID of the record | | | `sender_address` | string | No | The Own Number to be requested | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `INTERNATIONAL` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `OWN_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `status` | string | No | | Enum: `PENDING`, `REJECTED`, `APPROVED` | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests//verify" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "verification_code": "123456" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/requests//verify", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ verification_code: "123456" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized - **403**: Forbidden - **404**: Resource not found ## Related endpoints - [Request a Sender Address](https://developers.app.sinch.com/docs/api/source-address/request-sender-address-using-post.md) - [Get status of a sender address request](https://developers.app.sinch.com/docs/api/source-address/get-status-of-sender-address-request.md) - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) ## Specification details Complete the 2FA verification process required to register a Personal Number as a Sender ID. The following parameters are required for this request: - ```id:``` The UUID received in the API response of your request to the **Request a Sender Address** endpoint. - ```verification_code:``` The six-digit code received via SMS to the phone number that you are attempting to register [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/source-address/update-sender-address-using-patch.md # Update My Own Number Label Change the label assigned to an approved own-number sender address. | | | |---|---| | **Service** | [Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/{id}` | | **Operation ID** | `updateSenderAddressUsingPATCH` | | **Authentication** | Basic Auth, HMAC Auth | | **Success** | `200` — OK | | **Required** | `id`, `label` | ### Minimal request ```json { "label": "ExampleLabel" } ``` ## Authentication - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | Constraints | |------|------|----------|-------------|-------------| | `id` | string (uuid) | Yes | Sender address UUID (from GET .../addresses), not the request UUID | | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true - **Description:** Input the label need to update ### Schema (`PatchLabelMyOwnNumber`) | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `label` | string | Yes | Label need to be updated | Max length: 100 | ### Example request body ```json { "label": "ExampleLabel" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | OK | `GetSenderAddress` | | 400 | Bad Request | `400response` | | 401 | Unauthorized | None | | 403 | Forbidden | `403response` | | 404 | Resource not found | `404response` | ### 200 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `id` | string (uuid) | No | Approved sender address UUID (use for get, update, re-verify, and delete) | | | `sender_address` | string | No | The sender address value (alpha tag or phone number as a string) | | | `sender_address_type` | string | No | The Sender Address Type | Enum: `ALPHANUMERIC`, `INTERNATIONAL`, `SHORT_CODE` | | `usage_type` | string | No | The Sender Address Usage Type | Enum: `ALPHANUMERIC`, `OWN_NUMBER`, `DEDICATED`, `HOSTED_NUMBER` | | `destination_countries` | array of string | No | list of 2-character ISO country codes this sender address applies to | | | `reason` | string | No | | | | `label` | string | No | | | | `account_id` | string | No | | | | `created_date` | string (date-time) | No | | | | `last_modified_date` | string (date-time) | No | | | | `expiry` | string (date-time) | No | The Sender Address expiration time (apply for sender_address_type = OWN_NUMBER) | | | `display_status` | string | No | | Enum: `APPROVED`, `EXPIRED`, `EXPIRING` | ### 400 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | | `details` | array of string | Yes | Additional error detail messages. | | ### Example 400 response ```json { "message": "Request failed to parse correctly. Please ensure input is valid and try again.", "details": [ "Failed to parse message body." ] } ``` ### 403 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 403 response ```json { "message": "Invalid authentication credentials" } ``` ### 404 response schema | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `message` | string | Yes | | | ### Example 404 response ```json { "message": "Resource not found." } ``` ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "label": "ExampleLabel" }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/messaging/numbers/sender_address/addresses/", { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json", "Content-Type": "application/json" }, body: JSON.stringify({ label: "ExampleLabel" }) }); const result = await response.json(); console.log(result); ``` ## Error handling - **400**: Bad Request - **401**: Unauthorized - **403**: Forbidden - **404**: Resource not found ## Related endpoints - [Get all approved sender addresses](https://developers.app.sinch.com/docs/api/source-address/get-all-approved-sender-addresses.md) - [Get sender address by id](https://developers.app.sinch.com/docs/api/source-address/get-sender-address-by-id.md) - [Re-verify Sender Address](https://developers.app.sinch.com/docs/api/source-address/re-verify-sender-address-using-post.md) ## Specification details Update label for my own number only. The path `id` must be the **sender address** UUID from **Get all approved sender addresses**, not the request UUID. [← Source Address](https://developers.app.sinch.com/docs/api/source-address/index.md) --- ### Source: docs/api/webhooks-management/create-webhook.md # Create webhook Create a webhook for one or more of the specified events. A webhook would typically have the following structure: ```json { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ``` A valid webhook must consist of the following properties: - `url` The configured URL which will trigger the webhook when a selected event occurs. - `method` The methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests. - `encoding` Webhooks can be delivered using different content types. You can choose from `JSON`, `FORM_ENCODED` or `XML`. This will automatically add the Content-Type header for you so you don't have to add it again in the `headers` property. - `headers` HTTP header fields which provide required information about the request or response, or about the object sent in the message body. This should NOT include the `Content-Type` header. - `events` Event or events that will trigger the webhook. At least one event should be present. - `template` The structure of the payload that will be returned. You can format this in JSON or XML. - `read_timeout` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000. - `retries` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000. - `retry_delay` (Optional) The delay period between retries in seconds. Minimum of 5, max 60. #### Types of Events You can select all of the events (listed below) or combine them in whatever way you like but at least one event must be used. Otherwise, the webhook won't be created. A webhook will be triggered when any one or more of the events occur: + **SMS** + `RECEIVED_SMS` Receive an SMS + `OPT_OUT_SMS` Opt-out occurred + **MMS** + `RECEIVED_MMS` Receive an MMS + **DR (Delivery Reports)** + `ENROUTE_DR` Message is enroute + `EXPIRED_DR` Message has expired + `REJECTED_DR` Message is rejected + `FAILED_DR` Message has failed + `DELIVERED_DR` Message is delivered + `SUBMITTED_DR` Message is submitted #### Template Parameters You can choose what to include in the data that will be sent as the payload via the Webhook. It's up to you to choose what format you would like the payload to be returned. You can choose between JSON or XML. Keep in mind, if you've chosen JSON as the format, you must escape the JSON in the template value (see example above). | Data | Parameter Name | Example | Event Type | |------|----------------|---------|------------| | Service Type | `$format`, `$type` *- `$type` will be deprecated in the future; use `$format` instead* | `SMS` | DR, MO, MO MMS | | Message ID | `$mtId`, `$messageId` | `877c19ef-fa2e-4cec-827a-e1df9b5509f7` | DR, MO, MO MMS | | Delivery Report ID | `$drId`, `$reportId` | `01e1fa0a-6e27-4945-9cdb-18644b4de043` | DR | | Reply ID | `$moId`, `$replyId` | `a175e797-2b54-468b-9850-41a3eab32f74` | MO, MO MMS | | Account ID | `$accountId` | `DeveloperPortal7000` | DR, MO, MO MMS | | Message Timestamp | `$submittedTimestamp` | `2016-12-07T08:43:00.850Z` | DR, MO, MO MMS | | Provider Timestamp | `$receivedTimestamp` | `2016-12-07T08:44:00.850Z` | DR, MO, MO MMS | | Message Status | `$status` | `enroute` | DR | | Status Code | `$statusCode` | `200` | DR | | External Metadata | `$metadata.get('key')` | `name` | DR, MO, MO MMS | | Source Address | `$sourceAddress` | `+61491570156` | DR, MO, MO MMS | | Destination Address | `$destinationAddress` | `+61491593156` | MO, MO MMS | | Message Content | `$mtContent`, `$messageContent`, `$esc.json($!mtContent)` *- when used in `JSON` encoded `template`* | `Hi Derp` | DR, MO, MO MMS | | Reply Content | `$moContent`, `$replyContent`, `$esc.json($!moContent)` *- when used in `JSON` encoded `template`* | `Hello Derpina` | MO, MO MMS | | Retry Count | `$retryCount` | `1` | DR, MO, MO MMS | | Billing Unit | `$billingUnits` | `1` | DR | | Attachments | `$attachments` | See spec for JSON template example | MO MMS | #### Message Statuses Delivery Reports indicate message status. A message can have one of the following statuses: * `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed). * `submitted`: Message has been submitted to a provider/carrier for delivery. * `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible). * `expired`: The message has expired. * `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered * `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider. #### Message Status Codes Status codes provide more granular insight into a message's status. A message can have one of the following status codes: * `101`: Message being processed by the gateway. * `102`: Message is being rerouted to a different provider after failing via the first provider. * `151`: Message held for screening. * `200`: Message submitted to downstream provider for delivery. * `210`: Message accepted by downstream provider. * `211`: Message is enroute for delivery by provider. * `212`: Message submitted. Delivery pending. * `213`: Message scheduled for delivery by downstream provider. * `220`: Message delivered. * `221`: Message delivered to the handset. * `320`: Message validity period has expired (prior to submission). * `401`: Message validity period has expired (before delivery). * `301`: Usage threshold reached. Message discarded. * `302`: Destination address blocked. Message discarded. * `303`: Source address blocked. Message discarded. * `304`: Message dropped. Contact support. * `305`: Message discarded due to duplicate detection. * `402`: Message rejected by downstream provider. * `403`: Message skipped by downstream provider. * `410`: Invalid source address. * `411`: Invalid destination address. * `412`: Destination address blocked. * `413`: SMS service unavailable on destination. * `414`: Destination unreachable. * `330`: Gateway failure. * `331`: Message discarded. * `332`: No available route to destination. * `333`: Source address unsupported for this destination. * `400`: Message failed; undeliverable. * `405`: Message cancelled or deleted by provider. *Note: A 400 response will be returned if the request body cannot be parsed, the `url` is invalid (for example, malformed hostname or DNS syntax, unsupported scheme such as `ftp`, or path containing whitespace or control characters — e.g. `https://-invalid.com`, `https://invalid_.com`, `https:///path`, `https://:/path`, `http://.example.com`, `http://example..com`), an `events` value is not recognised (e.g. `RECEIVED_123`), the `events`, `encoding` or `method` is null, or the `headers` has a Content-Type attribute.* | | | |---|---| | **Service** | [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) | | **Method** | `POST` | | **URL** | `https://eu.app.api.sinch.com/v1/webhooks/messages` | | **Operation ID** | `CreateWebhook` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true | Property | Type | Required | Description | |----------|------|----------|-------------| | `url` | string | Yes | HTTP(S) URL for the webhook endpoint. Must use the `http` or `https` scheme. Hostnames must conform to RFC 1123 DNS name syntax. Paths must not contain whitespace or control characters. Invalid URLs are rejected with HTTP 400. Max length: 1000. | | `method` | string | Yes | HTTP method used when invoking the webhook. Enum: `GET`, `POST`, `PATCH`, `PUT`, `DELETE` | | `encoding` | string | Yes | Content encoding for the webhook request body. Enum: `JSON`, `FORM_ENCODED`, `XML` | | `events` | array of strings | Yes | Non-empty set of webhook event types to subscribe to. Minimum items: 1. | | `headers` | object | No | Optional map of custom headers. Content-Type header is not allowed. Key max length is 200 characters, value max length is 1000 characters. | | `template` | string | No | Optional Velocity template for the webhook request body. | | `read_timeout` | integer | No | The read timeout for the webhook call in milliseconds (1-60000). | | `retries` | integer | No | The number of times to retry a failed webhook call (0-5). | | `retry_delay` | integer | No | The delay between retries in seconds (5-60). | ### Example request body ```json { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 201 | Webhook successfully created | `CreateWebhookresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `UpdateWebhook400response` | | 401 | No valid authentication details were provided | — | | 409 | Unexpected error in API call. See HTTP response body for details. | `UpdateWebhook400response` | ### 201 response schema Webhook response object. No fields are strictly required in the schema; however, `id`, `url`, `method`, and `retries` are consistently populated. | Property | Type | Description | |----------|------|-------------| | `id` | string (uuid) | Unique identifier for the webhook. Always present. | | `url` | string | HTTP(S) URL for the webhook endpoint. Always present. | | `method` | string | HTTP method used when invoking the webhook. Always present. | | `encoding` | string | Content encoding. Usually present; can be null if missing/unknown. | | `headers` | object | Custom headers configured for the webhook. May be empty. | | `events` | array of strings | Webhook event types subscribed to. May be empty. | | `template` | string | Velocity template for the webhook request body. Only present if set. | | `read_timeout` | integer | The read timeout in milliseconds. Only present if set. | | `retries` | integer | The number of retry attempts. Always present (defaults to 0). | | `retry_delay` | integer | The delay between retries in seconds. Only present when retries are configured. | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | No | Additional error detail messages. | #### Example 400 responses **Invalid URL** ```json { "message": "Bad Request", "details": [ "/url: Not a valid http url" ] } ``` **Unrecognised event type** ```json { "message": "Bad Request", "details": [ "/events/0: [RECEIVED_123] is invalid" ] } ``` **Unparseable request body** ```json { "message": "Bad Request", "details": [ "Failed to parse message body." ] } ``` ### 409 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | No | Additional error detail messages. | ## Examples ### cURL ```bash curl -X POST "https://eu.app.api.sinch.com/v1/webhooks/messages" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -d '{ "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": ["ENROUTE_DR", "DELIVERED_DR"], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 }' ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/webhooks/messages", { method: "POST", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json" }, body: JSON.stringify({ url: "http://webhook.com", method: "POST", encoding: "JSON", headers: {}, events: ["ENROUTE_DR", "DELIVERED_DR"], template: '{"id":"$mtId","status":"$statusCode"}', read_timeout: 5000, retries: 3, retry_delay: 30 }) }); const webhook = await response.json(); console.log(webhook); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. Returned when the request body cannot be parsed, the `url` is invalid (malformed hostname or DNS syntax, unsupported scheme, or invalid path), an `events` value is not recognised, the `events`, `encoding` or `method` is null, or the `headers` has a Content-Type attribute (per operation note). Example responses: - Invalid URL: `"details": ["/url: Not a valid http url"]` - Unrecognised event: `"details": ["/events/0: [RECEIVED_123] is invalid"]` - Unparseable body: `"details": ["Failed to parse message body."]` - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **409 Conflict**: Unexpected error in API call. See HTTP response body for details. Example message: `A webhook with the given url and method already exists.` ## Related endpoints - [Retrieve webhook](https://developers.app.sinch.com/docs/api/webhooks-management/retrieve-webhook.md) - [Update webhook](https://developers.app.sinch.com/docs/api/webhooks-management/update-webhook.md) - [Delete webhook](https://developers.app.sinch.com/docs/api/webhooks-management/delete-webhook.md) [← Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) --- ### Source: docs/api/webhooks-management/delete-webhook.md # Delete webhook Delete a webhook that was previously created for the connected account. A webhook can be deleted by appending the UUID of the webhook to the endpoint and submitting a DELETE request. A successful request will return a `204 No Content` response with no body. | | | |---|---| | **Service** | [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) | | **Method** | `DELETE` | | **URL** | `https://eu.app.api.sinch.com/v1/webhooks/messages/{webhookId}` | | **Operation ID** | `DeleteWebhook` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `webhookId` | string (uuid) | Yes | Unique identifier of the webhook. Example: `7ca628a8-08b0-4e42-aeb8-960b37049c31` | ### Query parameters None. ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 204 | Webhook deleted successfully | — | | 401 | No valid authentication details were provided | — | | 404 | Not found. | — | ### 204 response No response body is returned on successful deletion. ## Examples ### cURL ```bash curl -X DELETE "https://eu.app.api.sinch.com/v1/webhooks/messages/76fa7010-8c1f-4a24-917a-4d62a54e744d" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" ``` ### JavaScript (fetch) ```javascript const webhookId = "76fa7010-8c1f-4a24-917a-4d62a54e744d"; const response = await fetch(`https://eu.app.api.sinch.com/v1/webhooks/messages/${webhookId}`, { method: "DELETE", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET") } }); if (response.status === 204) { console.log("Webhook deleted successfully"); } ``` ## Error handling - **401 Unauthorized**: No valid authentication details were provided. - **404 Not Found**: The specified webhook ID does not exist or belongs to a different account. Only pre-created webhooks can be deleted. ## Related endpoints - [Create webhook](https://developers.app.sinch.com/docs/api/webhooks-management/create-webhook.md) - [Retrieve webhook](https://developers.app.sinch.com/docs/api/webhooks-management/retrieve-webhook.md) - [Update webhook](https://developers.app.sinch.com/docs/api/webhooks-management/update-webhook.md) [← Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) --- ### Source: docs/api/webhooks-management/index.md # Webhooks Management Webhooks Management API allows you to manage your webhooks configuration. You can subscribe to one or several events, retrieve the webhooks, update them or even delete them if needed. ## Base URLs | Environment | URL | |-------------|-----| | EU instance | `https://eu.app.api.sinch.com` | | APAC instance | `https://au.app.api.sinch.com` | ## Endpoints | Endpoint | Method | Path | Description | |----------|--------|------|-------------| | [Create webhook](https://developers.app.sinch.com/docs/api/webhooks-management/create-webhook.md) | `POST` | `/v1/webhooks/messages` | Create a webhook for one or more of the specified events | | [Retrieve webhook](https://developers.app.sinch.com/docs/api/webhooks-management/retrieve-webhook.md) | `GET` | `/v1/webhooks/messages` | Retrieve all the webhooks created for the connected account | | [Update webhook](https://developers.app.sinch.com/docs/api/webhooks-management/update-webhook.md) | `PATCH` | `/v1/webhooks/messages/{webhookId}` | Update a webhook | | [Delete webhook](https://developers.app.sinch.com/docs/api/webhooks-management/delete-webhook.md) | `DELETE` | `/v1/webhooks/messages/{webhookId}` | Delete a webhook that was previously created for the connected account | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/api/webhooks-management/retrieve-webhook.md # Retrieve webhook Retrieve all the webhooks created for the connected account. A successful request will return a paginated response body as follows: ```json { "page": 0, "pageSize": 100, "pageData": [ { "id": "76fa7010-8c1f-4a24-917a-4d62a54e744d", "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ] } ``` | | | |---|---| | **Service** | [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) | | **Method** | `GET` | | **URL** | `https://eu.app.api.sinch.com/v1/webhooks/messages` | | **Operation ID** | `RetrieveWebhook` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters None. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | integer (int32) | No | Page number for pagination (0-based). Example: `0` | | `page_size` | integer (int32) | No | Number of results per page. Example: `20` | ### Header parameters None. ## Request body None. ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Successful response. | `RetrieveWebhookresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `UpdateWebhook400response` | | 401 | No valid authentication details were provided | — | ### 200 response schema | Property | Type | Description | |----------|------|-------------| | `page` | integer (int32) | The current page number. | | `pageSize` | integer (int32) | The number of webhooks returned per page. | | `pageData` | array | The list of webhooks created for the connected account. | #### `pageData` item schema Webhook response object. No fields are strictly required in the schema; however, id, url, method, and retries are consistently populated. | Property | Type | Description | |----------|------|-------------| | `id` | string (uuid) | Unique identifier for the webhook. Always present. | | `url` | string | HTTP(S) URL for the webhook endpoint. Always present. | | `method` | string | HTTP method used when invoking the webhook. Always present. | | `encoding` | string | Content encoding. Usually present; can be null if missing/unknown. | | `headers` | object | Custom headers configured for the webhook. May be empty. | | `events` | array of strings | Webhook event types subscribed to. May be empty. | | `template` | string | Velocity template for the webhook request body. Only present if set. | | `read_timeout` | integer | The read timeout in milliseconds. Only present if set. | | `retries` | integer | The number of retry attempts. Always present (defaults to 0). | | `retry_delay` | integer | The delay between retries in seconds. Only present when retries are configured. | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | — | ## Examples ### cURL ```bash curl -X GET "https://eu.app.api.sinch.com/v1/webhooks/messages?page=0&page_size=20" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Accept: application/json" ``` ### JavaScript (fetch) ```javascript const response = await fetch("https://eu.app.api.sinch.com/v1/webhooks/messages?page=0&page_size=20", { method: "GET", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Accept": "application/json" } }); const result = await response.json(); console.log(result.pageData); ``` ## Error handling - **400 Bad Request**: Returned when the `page` query parameter is not valid or the `pageSize` query parameter is not valid. - **401 Unauthorized**: No valid authentication details were provided. ## Related endpoints - [Create webhook](https://developers.app.sinch.com/docs/api/webhooks-management/create-webhook.md) - [Update webhook](https://developers.app.sinch.com/docs/api/webhooks-management/update-webhook.md) - [Delete webhook](https://developers.app.sinch.com/docs/api/webhooks-management/delete-webhook.md) [← Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) --- ### Source: docs/api/webhooks-management/update-webhook.md # Update webhook Update a webhook. You can update individual attributes or all of them by submitting a PATCH request. **All fields in the request body are optional, but at least one must be provided.** An empty body or a body with all null fields will be rejected. A successful request will return a response body as follows: ```json { "id": "76fa7010-8c1f-4a24-917a-4d62a54e744d", "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ``` *Note: Only pre-created webhooks can be updated. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.* *Note: A 400 response will be returned if the request body cannot be parsed, the `url` is invalid (for example, malformed hostname or DNS syntax, unsupported scheme such as `ftp`, or path containing whitespace or control characters — e.g. `https://-invalid.com`, `https://invalid_.com`, `https:///path`, `https://:/path`, `http://.example.com`, `http://example..com`), an `events` value is not recognised (e.g. `RECEIVED_123`), the `events`, `encoding` or `method` is null, or the `headers` has a Content-Type attribute.* | | | |---|---| | **Service** | [Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) | | **Method** | `PATCH` | | **URL** | `https://eu.app.api.sinch.com/v1/webhooks/messages/{webhookId}` | | **Operation ID** | `UpdateWebhook` | | **Authentication** | Basic Auth, HMAC Auth | ## Authentication This endpoint supports two authentication methods: - **Basic Auth**: HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide. - **HMAC Auth**: HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide. ## Parameters ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `webhookId` | string (uuid) | Yes | Unique identifier of the webhook. Example: `7ca628a8-08b0-4e42-aeb8-960b37049c31` | ### Query parameters None. ### Header parameters None. ## Request body - **Content-Type:** `application/json` - **Required:** true All fields are optional, but at least one must be provided. Empty body (all fields null) is rejected. > **Note:** `read_timeout`, `retries`, and `retry_delay` are not supported on update (create-only fields). | Property | Type | Required | Description | |----------|------|----------|-------------| | `url` | string | No | HTTP(S) URL for the webhook endpoint. Must use the `http` or `https` scheme. Hostnames must conform to RFC 1123 DNS name syntax. Paths must not contain whitespace or control characters. Invalid URLs are rejected with HTTP 400. Max length: 1000. | | `method` | string | No | HTTP method used when invoking the webhook. Enum: `GET`, `POST`, `PATCH`, `PUT`, `DELETE` | | `encoding` | string | No | Content encoding for the webhook request body. Enum: `JSON`, `FORM_ENCODED`, `XML` | | `headers` | object | No | Optional map of custom headers. Content-Type header is not allowed. Key max length is 200 characters, value max length is 1000 characters. | | `template` | string | No | Velocity template for the webhook request body. | | `events` | array of strings | No | Webhook event types to subscribe to. If provided, must be non-empty (events: [] is rejected). | ### Example request body ```json { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" } ``` ## Responses | Status | Description | Schema | |--------|-------------|--------| | 200 | Webhook updated successfully | `CreateWebhookresponse` | | 400 | Unexpected error in API call. See HTTP response body for details. | `UpdateWebhook400response` | | 401 | No valid authentication details were provided | — | | 404 | Not found. | — | ### 200 response schema Webhook response object. No fields are strictly required in the schema; however, `id`, `url`, `method`, and `retries` are consistently populated. | Property | Type | Description | |----------|------|-------------| | `id` | string (uuid) | Unique identifier for the webhook. Always present. | | `url` | string | HTTP(S) URL for the webhook endpoint. Always present. | | `method` | string | HTTP method used when invoking the webhook. Always present. | | `encoding` | string | Content encoding. Usually present; can be null if missing/unknown. | | `headers` | object | Custom headers configured for the webhook. May be empty. | | `events` | array of strings | Webhook event types subscribed to. May be empty. | | `template` | string | Velocity template for the webhook request body. Only present if set. | | `read_timeout` | integer | The read timeout in milliseconds. Only present if set. | | `retries` | integer | The number of retry attempts. Always present (defaults to 0). | | `retry_delay` | integer | The delay between retries in seconds. Only present when retries are configured. | ### 400 response schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `message` | string | Yes | | | `details` | array of strings | No | Additional error detail messages. | #### Example 400 responses **Invalid URL** ```json { "message": "Bad Request", "details": [ "/url: Not a valid http url" ] } ``` **Unrecognised event type** ```json { "message": "Bad Request", "details": [ "/events/0: [RECEIVED_123] is invalid" ] } ``` **Unparseable request body** ```json { "message": "Bad Request", "details": [ "Failed to parse message body." ] } ``` ## Examples ### cURL ```bash curl -X PATCH "https://eu.app.api.sinch.com/v1/webhooks/messages/76fa7010-8c1f-4a24-917a-4d62a54e744d" \ -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \ -H "Content-Type: application/json" \ -d '{ "url": "http://new-webhook-url.com", "events": ["DELIVERED_DR", "FAILED_DR"] }' ``` ### JavaScript (fetch) ```javascript const webhookId = "76fa7010-8c1f-4a24-917a-4d62a54e744d"; const response = await fetch(`https://eu.app.api.sinch.com/v1/webhooks/messages/${webhookId}`, { method: "PATCH", headers: { "Authorization": "Basic " + btoa("API_KEY:API_SECRET"), "Content-Type": "application/json" }, body: JSON.stringify({ url: "http://new-webhook-url.com", events: ["DELIVERED_DR", "FAILED_DR"] }) }); const webhook = await response.json(); console.log(webhook); ``` ## Error handling - **400 Bad Request**: Unexpected error in API call. See HTTP response body for details. Returned when the request body cannot be parsed, the `url` is invalid (malformed hostname or DNS syntax, unsupported scheme, or invalid path), an `events` value is not recognised, the `events`, `encoding` or `method` is null, the `headers` has a Content-Type attribute, the body is empty, all fields are null, or `events: []` is supplied (per operation note). Example responses: - Invalid URL: `"details": ["/url: Not a valid http url"]` - Unrecognised event: `"details": ["/events/0: [RECEIVED_123] is invalid"]` - Unparseable body: `"details": ["Failed to parse message body."]` - **401 Unauthorized**: No valid authentication details were provided. Verify Basic or HMAC credentials on the request. - **404 Not Found**: Not found. Returned when an invalid or non existent `webhookId` is specified in the request (per operation note). ## Related endpoints - [Create webhook](https://developers.app.sinch.com/docs/api/webhooks-management/create-webhook.md) - [Retrieve webhook](https://developers.app.sinch.com/docs/api/webhooks-management/retrieve-webhook.md) - [Delete webhook](https://developers.app.sinch.com/docs/api/webhooks-management/delete-webhook.md) [← Webhooks Management](https://developers.app.sinch.com/docs/api/webhooks-management/index.md) --- ### Source: docs/guides/ai-integration.md # AI Integration How to point an AI assistant, coding agent, or crawler at the Sinch Engage API documentation so it gets accurate, current answers instead of guessing. Everything below is published on every docs build, so it never drifts from the reference you are reading now. Nothing requires an API key — these are public URLs. ## What's published | Artifact | URL | Use it for | |----------|-----|-----------| | Curated index | [`/llms.txt`](https://developers.app.sinch.com/llms.txt) | The starting point. A small (1,000–3,000 token) plain-text map of the API: authentication, every service, code samples, guides. Fetch this first. | | Full documentation | [`/llms-full.txt`](https://developers.app.sinch.com/llms-full.txt) | Every reference and guide page inlined in one file, each behind a stable anchor. Use it when you want the whole corpus in context or as an uploaded file. | | Per-page Markdown | `/docs/api//.md`
`/docs/guides/.md` | One clean Markdown file per operation — no HTML, no navigation chrome. Best for retrieving just the endpoint you're working on. | | OpenAPI specification | [`/openapi.yaml`](https://developers.app.sinch.com/openapi.yaml) · [`/openapi.json`](https://developers.app.sinch.com/openapi.json) | Machine-readable request/response schemas, enums, and constraints. The authoritative contract when generating or validating code. | Index pages list what exists: [`/docs/api/index.md`](https://developers.app.sinch.com/docs/api/index.md) for the API reference and [`/docs/guides/index.md`](https://developers.app.sinch.com/docs/guides/index.md) for guides. **Example** — the Markdown for the send-messages endpoint: ```plain https://developers.app.sinch.com/docs/api/messages/send-messages.md ``` ## Discovery If you build a crawler or agent, you don't need to hard-code the paths above. Every page of the API reference declares them in its ``: ```html ``` `rel="describedby"` is the discovery relation defined by llms.txt v2 and is the one to match on. The two `rel="alternate"` tags carry the same targets and are kept for agents written against the earlier convention. The OpenAPI document points at the same index from its root `externalDocs`, so a tool that starts from the specification can find the prose docs too: ```yaml externalDocs: description: Agent-readable curated docs index (llms.txt) url: https://developers.app.sinch.com/llms.txt ``` ## Point your tool at the docs ### Any agent or script Fetch the curated index first, then follow only the links you need. This keeps context small and avoids ingesting the whole corpus for a one-endpoint question: ```bash curl -s https://developers.app.sinch.com/llms.txt curl -s https://developers.app.sinch.com/docs/api/messages/send-messages.md ``` Use `/openapi.yaml` when you need exact schemas — field names, types, enums, and limits — for code generation or request validation. ### Claude Code Ask it to read the index, and it will follow the links from there: ```plain Read https://developers.app.sinch.com/llms.txt, then show me how to send an SMS with a delivery report using Basic Authentication. ``` To make it available in every session of a project, add a line to your `CLAUDE.md`: ```markdown Sinch Engage API docs: https://developers.app.sinch.com/llms.txt (start here), full corpus at /llms-full.txt, OpenAPI at /openapi.yaml. ``` ### Cursor Add the docs once, then reference them with `@Docs`: 1. **Settings → Indexing & Docs → Add Doc** 2. Enter `https://developers.app.sinch.com/llms-full.txt` 3. Name it `Sinch Engage`, then use `@Docs Sinch Engage` in chat or Composer. ### ChatGPT Paste the index URL in the conversation and let it browse: ```plain Using https://developers.app.sinch.com/llms.txt as the source of truth, write a Node.js function that polls for replies. ``` For a Project or a custom GPT that should always have the docs on hand, download `llms-full.txt` and upload it as a knowledge file instead. ### Perplexity Include the URL in the question so the answer is grounded in the docs rather than the open web: ```plain https://developers.app.sinch.com/llms-full.txt — what are the required headers for HMAC authentication on this API? ``` ### Other tools Anything that accepts a documentation URL or an uploaded text file works: point it at `/llms.txt` for a map, or `/llms-full.txt` for the complete text. ## On-page actions Each section of the API reference has two links next to its heading: - **Copy for LLM** — copies that section as Markdown to your clipboard, ready to paste into a chat. - **View as Markdown** — opens that section's raw `.md` file, so you can copy the URL for an agent to fetch. ## Versioning The Sinch Engage API's supported surface is `/v1/`, so the published artifacts are the root ones listed above — there is a single `/llms.txt`, and it always describes the current stable version. A handful of Messaging Reports endpoints are pre-release under `/v2-preview/`. They appear in the reference and are marked as preview, but they do not get their own index while their contract can still change. When a new major version is promoted out of preview it will be published as a version-scoped variant (for example `/v2/llms.txt`), and the root `/llms.txt` will continue to track the current stable version. Regeneration happens on every documentation publish, so a cached copy of any artifact can go stale. Re-fetch rather than relying on a stored snapshot, and treat `/openapi.yaml` as the authoritative contract if a prose page and the specification ever disagree. ## Related - [Basic Authentication](https://developers.app.sinch.com/docs/guides/basic-authentication.md) — the simplest way to authenticate the requests your agent generates. - [HMAC Authentication](https://developers.app.sinch.com/docs/guides/hmac-authentication.md) — request signing, if you need it. - [Sub-accounts](https://developers.app.sinch.com/docs/guides/sub-accounts.md) — acting on behalf of a sub-account. [← All guides](https://developers.app.sinch.com/docs/guides/index.md) --- ### Source: docs/guides/basic-authentication.md # Basic Authentication Every request requires an `Authorization` header in the following format: ```plain Authorization: Basic Base64(api_key:api_secret) ``` Where the header consists of the `Basic` keyword followed by your Basic Authentication `api_key` and `api_secret` (supplied by Sinch support), separated by a colon (`:`) and then Base64-encoded. ## Example request with Basic Authentication ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "format": "SMS" } ] } ``` _Note: spaces are used as indentation in the body of the above request._ ## Related - [HMAC Authentication](https://developers.app.sinch.com/docs/guides/hmac-authentication.md) — an alternative to Basic Auth using a request signature. - [Sub-accounts](https://developers.app.sinch.com/docs/guides/sub-accounts.md) — send on behalf of a sub-account using a parent account's credentials. [← All guides](https://developers.app.sinch.com/docs/guides/index.md) --- ### Source: docs/guides/hmac-authentication.md # HMAC Authentication Every request requires an `Authorization` header in one of the following formats. For a request **with** a request body: ```plain Authorization: hmac username="", algorithm="hmac-sha256", headers="Date Content-MD5 request-line", signature="" ``` For a request **without** a request body: ```plain Authorization: hmac username="", algorithm="hmac-sha256", headers="Date request-line", signature="" ``` ## To create this header ### Step 1 Add a `Date` header to the request using the current date time in [RFC 7231 Section 7.1.1.2](http://tools.ietf.org/html/rfc7231#section-7.1.1.2) format. ### Step 2 If the request has a body, add a header called `Content-MD5` where the value is an MD5 hash of the request body; otherwise this header is not required. ### Step 3 Create a signing string by concatenating the `Date` header, the `Content-MD5` header (if set), and the request line with line breaks: ```plain Date: Sat, 30 Jul 2016 05:13:23 GMT\nContent-MD5: 10fd4feab20d38432480c07301e49616\nPOST /v1/messages HTTP/1.1 ``` or, for a request without a body: ```plain Date: Sat, 30 Jul 2016 05:13:23 GMT\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1 ``` ### Step 4 Create a SHA256 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8): `HMAC-SHA256(signing string, secret)`. ### Step 5 Base64-encode the HMAC hash and include it as the signature in the `Authorization` header. ## Example request with body ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Date: Sat, 30 Jul 2016 05:18:52 GMT Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha256", headers="Date Content-MD5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA=" Content-MD5: 5407644fa83bec240dede971307e0cad Content-Length: 133 { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "format": "SMS" } ] } ``` _Note: spaces are used as indentation in the body of the above request._ ## Example request without body ```plain GET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Date: Sat, 30 Jul 2016 05:18:52 GMT Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha256", headers="Date request-line", signature="NTUwMjUwNTVmZGYzZTIxODMyYjc1ZmM3M2EwZWQ1NzA3NzA4ZTZjNw==" ``` ## Related - [Basic Authentication](https://developers.app.sinch.com/docs/guides/basic-authentication.md) — a simpler alternative using a Base64-encoded key/secret. - [Sub-accounts](https://developers.app.sinch.com/docs/guides/sub-accounts.md) — send on behalf of a sub-account using a parent account's credentials. [← All guides](https://developers.app.sinch.com/docs/guides/index.md) --- ### Source: docs/guides/index.md # Guides Cross-cutting guides that apply across the Sinch Engage API, rather than to a single endpoint. | Guide | Description | |-------|-------------| | [Basic Authentication](https://developers.app.sinch.com/docs/guides/basic-authentication.md) | Authenticate requests with a Base64-encoded API key/secret. | | [HMAC Authentication](https://developers.app.sinch.com/docs/guides/hmac-authentication.md) | Authenticate requests by signing them with an HMAC-SHA256 signature. | | [Sub-accounts](https://developers.app.sinch.com/docs/guides/sub-accounts.md) | Perform actions on behalf of a sub-account using a parent account's API key. | | [AI Integration](https://developers.app.sinch.com/docs/guides/ai-integration.md) | Point AI assistants and coding agents at the agent-readable copies of these docs. | [← All services](https://developers.app.sinch.com/docs/api/index.md) --- ### Source: docs/guides/sub-accounts.md # Sub-accounts ## Performing actions on behalf of sub-accounts Using API keys at the parent account level, you can perform actions on behalf of a sub-account. This feature is supported by the Messages, Replies, Delivery Reports, and Webhooks APIs. Source Address also supports it, on all of its endpoints (see its own documentation). To do this, include a header key `Account` with the sub-account ID as the value. For example: ```plain Account: mySubAccount ``` ## Example request sending from a sub-account ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp Account: SubAccount { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "delivery_report": true } ] } ``` This is different from **creating or deleting** sub-accounts. Reseller account lifecycle (create sub-account, add Sinch Engage users, delete account) is documented under [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md). ## Related - [Basic Authentication](https://developers.app.sinch.com/docs/guides/basic-authentication.md) - [HMAC Authentication](https://developers.app.sinch.com/docs/guides/hmac-authentication.md) - [Account Management](https://developers.app.sinch.com/docs/api/account-management/index.md) [← All guides](https://developers.app.sinch.com/docs/guides/index.md) ---