# US 10DLC API Installation 10DLC is a local 10-digit phone number that requires Brand & Use Case registration and supports throughput levels suitable for A2P SMS campaigns. 10DLC is sanctioned by mobile carriers for A2P messaging and is intended to provide a reliable user experience, better deliverability, and higher messaging speed. To find out more about 10DLC see the following [page](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc) To setup a new channel to send SMS messages using a United states 10 digit long code number the following steps are required {% hint style="warning" %} Some of the following requests will lead to additional workspace charges. Ensure you [understand the costs](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/additional-costs-for-using-10dlc) before proceeding {% endhint %} ## API Access The following API requests can only be made using a [valid access key](https://docs.bird.com/api/api-access/api-authorization) and attached to an [access role](https://docs.bird.com/api/api-access/access-roles) with the an [access policy](https://docs.bird.com/api/api-access/access-policies) that at least specifies the permissions to the resources outlined in each section below. ## Find an available number If you do not already have a US 10DLC number available in your workspace you can find one to purchase .You can filter by country, prefix, number type and number capabilities. ## GET /organizations/{organizationId}/numbers-stock-items > List all available numbers in stock. ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage a number within a workspace.","name":"numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryLimit":{"description":"Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.\n","in":"query","name":"limit","schema":{"default":10,"maximum":99,"minimum":1,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryCountryCodes":{"allowEmptyValue":false,"in":"query","name":"countryCodes","schema":{"description":"A 2-digit ISO 3166-1 country code array.","items":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":"array"}},"queryLongCodeNumberTypes":{"allowEmptyValue":false,"description":"The number type depending on its purpose. Local for regional use, national for countrywide use, mobile for mobile networks, or toll-free for caller-free charging.","in":"query","name":"types","schema":{"items":{"$ref":"#/components/schemas/LongCodeNumberType"},"type":"array"}},"queryNumberFeatures":{"allowEmptyValue":false,"description":"The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.","in":"query","name":"features","schema":{"items":{"$ref":"#/components/schemas/NumberFilterFeature"},"minItems":1,"type":"array"}},"queryNumberPrefix":{"description":"Used to filter numbers by area code. Accepts either bare area code digits (e.g. `205` for Alabama) or a full E.164 prefix (e.g. `+1205`). Partial prefixes are supported for autocomplete use cases (e.g. `+120` matches all numbers in area codes 202, 203, 205, 206, 207, 208, 209). Must be used together with the `countryCodes` filter.","in":"query","name":"prefix","schema":{"maxLength":250,"minLength":1,"type":"string"}},"queryTesting":{"in":"query","name":"testing","schema":{"type":"boolean"}}},"schemas":{"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"LongCodeNumberType":{"type":"string","description":"The type of long code number.","enum":["local","national","toll-free","mobile"]},"NumberFilterFeature":{"type":"string","enum":["voice-outbound","voice-inbound","sms-outbound","sms-inbound","mms-outbound","mms-inbound","whatsapp"]},"NumberStockItem":{"type":"object","required":["id","countryCode","type","numberString","capabilities","monthlyPrice"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the stock item."},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"numberString":{"type":"string"},"capabilities":{"$ref":"#/components/schemas/PhoneNumberCapabilities"},"monthlyPrice":{"$ref":"#/components/schemas/Money"},"backOrderRequired":{"type":"boolean","description":"Whether back order is required for this item, available but it is not in the local inventory"},"backOrderStockId":{"type":"string","description":"The stock id of the back order item, to be used when creating back order","nullable":true}}},"PhoneNumberCapabilities":{"type":"object","description":"Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.","required":["voice","sms","mms"],"properties":{"voice":{"$ref":"#/components/schemas/PhoneNumberCapability"},"sms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"mms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"whatsapp":{"$ref":"#/components/schemas/PhoneNumberCapability"}}},"PhoneNumberCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"Money":{"type":"object","title":"Money","additionalProperties":false,"description":"Money combines an amount of money with its currency.","nullable":true,"properties":{"currencyCode":{"$ref":"#/components/schemas/Currency"},"amount":{"$ref":"#/components/schemas/Amount"},"exponent":{"$ref":"#/components/schemas/Exponent"}},"required":["currencyCode","amount","exponent"]},"Currency":{"title":"Currency Code","description":"Currency as ISO 4217 code (three digits). An example would be `EUR` for Euro.","type":"string","enum":["EUR","USD","GBP","AUD","SGD","IDR","INR","MXN"]},"Amount":{"type":"integer","format":"int64"},"Exponent":{"description":"Usually a negative number to specify the exponent for decimal precision. e.g., `1540 * (10^-2) = 15.4`","type":"integer","format":"int32","minimum":-10},"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.","type":"string"}},"type":"object"},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/organizations/{organizationId}/numbers-stock-items":{"get":{"operationId":"listOrganizationNumbersStockItems","summary":"List all available numbers in stock.","parameters":[{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryCountryCodes"},{"$ref":"#/components/parameters/queryLongCodeNumberTypes"},{"$ref":"#/components/parameters/queryNumberFeatures"},{"$ref":"#/components/parameters/queryNumberPrefix"},{"$ref":"#/components/parameters/queryTesting"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/NumberStockItem"},"type":"array"}},"required":["results"],"type":"object"},{"$ref":"#/components/schemas/pagination"}]}}},"description":"OK"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid filter"}},"tags":["numbers"]}}}} ``` ### Example {% tabs %} {% tab title="Request" %} The following example will return the first available US local number required for use with 10DLC registration. {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//numbers-available?limit=1&country=US&type=local' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' ``` {% endcode %} {% endtab %} {% endtabs %} ## Purchase a number Once you have found an available number you can purchase this by providing the number (in E.1624 format) and the country (using a two digit ISO code). {% hint style="warning" %} A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number {% endhint %} ## Buy Long Code Numbers > Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.
```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage long code numbers.","name":"long_code_numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWorkspaceLongCodeNumbers":{"type":"object","additionalProperties":false,"required":["numberStockItemIds"],"properties":{"numberStockItemIds":{"type":"array","maxItems":25,"description":"The unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time.\nThis operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.\n","items":{"type":"string","format":"uuid"}}}},"WorkspaceLongCodeNumber":{"type":"object","allOf":[{"$ref":"#/components/schemas/LongCodeNumberFragment"},{"type":"object","required":["endpoint"],"properties":{"endpoint":{"$ref":"#/components/schemas/EndpointFragment"}}}]},"LongCodeNumberFragment":{"type":"object","required":["id","endpointId","numberString","countryCode","capabilities","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the long code number. The endpoint ID is the same."},"endpointId":{"type":"string","format":"uuid","description":"The unique identifier of the endpoint. The long conde ID is the same."},"numberString":{"type":"string","description":"The phone number in E.164 format."},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"capabilities":{"$ref":"#/components/schemas/PhoneNumberCapabilities"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"order":{"$ref":"#/components/schemas/LongCodeNumberOrder","description":"The order that created this long code number. It contains information such as the capabilities, order status and type."},"deprovisionAt":{"type":"string","format":"date-time","description":"The date and time when the long code number should be deprovisioned."}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"LongCodeNumberType":{"type":"string","description":"The type of long code number.","enum":["local","national","toll-free","mobile"]},"PhoneNumberCapabilities":{"type":"object","description":"Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.","required":["voice","sms","mms"],"properties":{"voice":{"$ref":"#/components/schemas/PhoneNumberCapability"},"sms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"mms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"whatsapp":{"$ref":"#/components/schemas/PhoneNumberCapability"}}},"PhoneNumberCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"LongCodeNumberOrder":{"type":"object","required":["countryCode","type","capabilities","status","createdAt","updatedAt"],"properties":{"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}},"prefix":{"type":"string"},"status":{"$ref":"#/components/schemas/LongCodeNumberOrderStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"LongCodeNumberOrderStatus":{"type":"string","enum":["draft","submitted","processing","fulfilled","rejected","cancelled"]},"EndpointFragment":{"type":"object","description":"A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.","required":["id","type","instanceId","name","capabilities","provisioningStatus","createdAt","updatedAt"],"properties":{"id":{"$ref":"#/components/schemas/EndpointId"},"type":{"$ref":"#/components/schemas/EndpointType"},"instanceId":{"$ref":"#/components/schemas/InstanceId"},"name":{"$ref":"#/components/schemas/EndpointName"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapability"}},"dependencies":{"type":"array","description":"The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.","items":{"$ref":"#/components/schemas/EndpointDependency"}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}},"provisioningStatus":{"$ref":"#/components/schemas/EndpointProvisioningStatus"},"whatsApp":{"description":"WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.","nullable":true,"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointId":{"type":"string","format":"uuid","description":"The ID of the endpoint."},"EndpointType":{"type":"string","description":"The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.","enum":["long-code-number","short-code-number","alpha-number","ip-pool","rcs-google-agent"]},"InstanceId":{"type":"string","format":"uuid","description":"The unique identifier of the instance."},"EndpointName":{"type":"string","description":"The name of the endpoint. For some cases it will be the number in international format as string."},"EndpointCapability":{"type":"object","description":"The capability of the endpoint. It shows what capabilities the endpoint supports and which direction (inbound, which means receiving messages, and outbound, which means sending messages). Also, it shows the status for that capability/direction combination.","discriminator":{"propertyName":"name","mapping":{"sms":"#/components/schemas/EndpointCapabilitySMS","mms":"#/components/schemas/EndpointCapabilityMMS","voice":"#/components/schemas/EndpointCapabilityVoice","whatsapp":"#/components/schemas/EndpointCapabilityWhatsapp","email":"#/components/schemas/EndpointCapabilityEmail","rcs-google":"#/components/schemas/EndpointCapabilityRcsGoogle"}},"oneOf":[{"$ref":"#/components/schemas/EndpointCapabilitySMS"},{"$ref":"#/components/schemas/EndpointCapabilityMMS"},{"$ref":"#/components/schemas/EndpointCapabilityVoice"},{"$ref":"#/components/schemas/EndpointCapabilityWhatsapp"},{"$ref":"#/components/schemas/EndpointCapabilityEmail"},{"$ref":"#/components/schemas/EndpointCapabilityRcsGoogle"}]},"EndpointCapabilitySMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["sms"]}}}]},"EndpointCapabilityFields":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"inbound":{"$ref":"#/components/schemas/InboundEndpointCapability"},"outbound":{"$ref":"#/components/schemas/OutboundEndpointCapability"}}},"InboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"OutboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"destinationStatuses":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"},"available":{"type":"number"},"unavailable":{"type":"number"}}},"supportsDestinations":{"type":"boolean","description":"Whether the number supports destinations"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityMMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["mms"]}}}]},"EndpointCapabilityVoice":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["voice"]},"useCaseType":{"$ref":"#/components/schemas/EndpointVoiceUseCaseType"}}}]},"EndpointVoiceUseCaseType":{"type":"string","enum":["contact-centre"]},"EndpointCapabilityWhatsapp":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["whatsapp"]}}}]},"EndpointCapabilityEmail":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["email"]}}}]},"EndpointCapabilityRcsGoogle":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["rcs-google"]}}}]},"EndpointDependency":{"type":"object","discriminator":{"propertyName":"type","mapping":{"connector":"#/components/schemas/EndpointDependencyConnector"}},"oneOf":[{"$ref":"#/components/schemas/EndpointDependencyConnector"}]},"EndpointDependencyConnector":{"type":"object","required":["connectorId","connectorTemplateRef"],"properties":{"type":{"type":"string","enum":["connector"]},"connectorId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}}}},"EndpointProvisioningStatus":{"type":"string","enum":["provisioned","provisioning","deprovisioned","deprovisioning"]},"WorkspaceWhatsAppNumber":{"type":"object","description":"WhatsApp number pre-verification details.","properties":{"whatsAppId":{"type":"string"},"status":{"$ref":"#/components/schemas/WhatsAppNumberStatus"},"stage":{"type":"string"},"attempt":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"verificationExpiresAt":{"type":"string","format":"date-time","nullable":true},"requestedCodeAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WhatsAppNumberStatus":{"type":"string","description":"WhatsApp number status","enum":["unknown","already-exists","installed","verified","not-verified","expired"]},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/numbers-long-code":{"post":{"operationId":"createWorkspaceLongCodeNumbers","description":"Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceLongCodeNumbers"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/WorkspaceLongCodeNumber"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"Created"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Long Code Number not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Buy Long Code Numbers","tags":["long_code_numbers"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will purchase the number if it still available and you have sufficient balance in your workspace wallet. Provide number in E.1624 format and country in 2 digit ISO code (e.g. US) {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//numbers' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "numbers": [ { "number": "", "country": "" } ] }' ``` {% endcode %} {% endtab %} {% endtabs %} ## (Optional) Set up 10DLC webhook subscriptions You can set up a Web Hook subscription to be notified of any brand or campaign event. Brand and camping creation work in sync, and subscribing to all related events will automate the 10DLC registration process. ## Create a webhook subscription > To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\ > You can create multiple webhook subscriptions to route different types of events to various URLs as needed.\ > Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\ > If you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.
```json {"openapi":"3.0.3","info":{"title":"Notifications","version":"1.0.0"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWebhookSubscription":{"allOf":[{"type":"object","required":["service","event","url"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/WebhookEventFilter"},"description":"Filters to apply to the events that are sent to the webhook. This is a key-value list of filters that are specific to the service that the webhook is subscribed to.\nOne example would be a key of `channelId` and a value of a UUID (in string format) that represents a channel.\n"},"template":{"type":"string"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"}},"oneOf":[{"$ref":"#/components/schemas/EventFiltersChannels"},{"$ref":"#/components/schemas/EventFiltersNumbers"},{"$ref":"#/components/schemas/EventFiltersPayments"},{"$ref":"#/components/schemas/EventFiltersConversations"},{"$ref":"#/components/schemas/EventFiltersTemplates"}],"discriminator":{"propertyName":"service","mapping":{"channels":"#/components/schemas/EventFiltersChannels","numbers":"#/components/schemas/EventFiltersNumbers","payments":"#/components/schemas/EventFiltersPayments","conversations":"#/components/schemas/EventFiltersConversations","templates":"#/components/schemas/EventFiltersTemplates"}}}]},"WebhookService":{"type":"string","enum":["channels","numbers","payments","conversations","templates"],"description":"The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be `channels`.\n"},"WebhookEvent":{"type":"string","description":"The event name identifies the webhook event, such as `sms.outbound` for notifications about SMS messages being sent.\n"},"WebhookEventFilter":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId","platformId","channelStatus","interactionType","messageStatus","status","eventDestination","navigatorId"]},"value":{"type":"string"}},"description":"Filters used to narrow down events sent to the webhook. For example, if you want to receive events for a specific platform,\na valid filterKey would be `platformId` with a value of `sms`.\n"},"Url":{"type":"string","pattern":"^https://([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(/[^\\s]*)?$","description":"The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that respects the established pattern and is accessible from the internet.\n"},"SigningKey":{"type":"string","description":"The signing key for the webhook and can be used to verify the authenticity of the webhook.\n"},"EventFiltersChannels":{"type":"object","title":"Channels service filters","properties":{"service":{"type":"string","enum":["channels"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}},{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["messageStatus","interactionType","channelStatus","platformId","status"]},"value":{"type":"string"}}}]}}}},"EventFiltersNumbers":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["numbers"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"description":"The numbers service does not have any specific filters for its events.\n","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersPayments":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["payments"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersConversations":{"type":"object","title":"Conversations service filters","properties":{"service":{"type":"string","enum":["conversations"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}}]}}}},"EventFiltersTemplates":{"type":"object","title":"Templates service filters","properties":{"service":{"type":"string","enum":["templates"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["platformId"]},"value":{"type":"string"}}}]}}}},"WebhookSubscription":{"type":"object","required":["id","organizationId","workspaceId","service","event","url","status"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.\n"},"organizationId":{"$ref":"#/components/schemas/WebhookOrganizationId"},"workspaceId":{"$ref":"#/components/schemas/WebhookWorkspaceId"},"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventFilter"}},"template":{"$ref":"#/components/schemas/Template"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"},"status":{"$ref":"#/components/schemas/WebhookSubscriptionStatus"},"statusReason":{"type":"string","description":"A human-readable explanation for the current status of the webhook subscription.\n"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookOrganizationId":{"type":"string","format":"uuid"},"WebhookWorkspaceId":{"type":"string","format":"uuid"},"Template":{"type":"string","description":"Used for our Exit APIs for Twilio and Sinch.\nMore information can be found [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api) for Twilio and [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/sinch-exit-api) for Sinch.\n"},"WebhookSubscriptionStatus":{"type":"string","enum":["active","inactive"]},"errorResponse":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions":{"post":{"summary":"Create a webhook subscription","description":"To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\nYou can create multiple webhook subscriptions to route different types of events to various URLs as needed.\nEvent filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\nIf you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.\n","operationId":"createLegacyWebhookSubscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscription"}}}},"responses":{"201":{"description":"The webhook subscription was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Invalid HTTP request. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}},"422":{"description":"The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}}} ``` #### Brand Subscriptions The Following example will Create a subscrscrition listing to all Brand Related events ``` curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "signingKey": "my-signing-key", "eventFilters": [ ], "event": "10dlc.brand", "service": "numbers", "url": "" }' ``` #### Campaign Subscription The Following example will Create a subscription listing to all Brand Related events ``` curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "signingKey": "my-signing-key", "eventFilters": [ ], "event": "10dlc.campaign", "service": "numbers", "url": "" }' ``` ## Register a new brand with the campaign registry {% hint style="info" %} **A-Sync** : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result . {% endhint %} Before you can use a US 10DLC number to send SMS messages, you must be [register a brand](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/brand-registration) and campaign with an external registry called the campaign registry. After creating a brand, this will be submitted for approval by the campaign registry. The brand must be approved before you can register a campaign with the campaign registry. Brand registration may take some time. You can find the full list of brand management endpoints [here](https://docs.bird.com/api/numbers-api/api-reference/10dlc-compliance) {% hint style="warning" %} A successful request to this endpoint will mean you are charged a [brand registration](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/brand-registration) fee. If you later need to update or resubmit your brand there may be additional fees. {% endhint %} ## Create a brand at workspace level > Create a brand at workspace level. This means it will be available only for this workspace. A brand registration is mandatory due to compliance requirements.
```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"TCR Brands","name":"number_brands"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Workspace":{"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/BrandEntityType"},"firstName":{"maxLength":100,"type":"string","description":"First or given name. Applicable to entity type."},"lastName":{"maxLength":100,"type":"string","description":"Last or Surname. Applicable to entity type."},"displayName":{"minLength":1,"maxLength":255,"type":"string","description":"Display or marketing name your brand."},"companyName":{"minLength":1,"maxLength":255,"type":"string","description":"Legal company name. This should match the legal company name used to register your EIN/Tax ID."},"ein":{"minLength":1,"maxLength":21,"type":"string","description":"Government assigned corporate tax ID. EIN is 9-digits in the U.S."},"einIssuingCountry":{"minLength":1,"maxLength":2,"type":"string","description":"The 2 letter ISO country of registration submitted with your EIN / Tax ID registration."},"phone":{"minLength":1,"maxLength":20,"type":"string","description":"Valid phone number in e.164 international format."},"street":{"minLength":1,"maxLength":100,"type":"string","description":"Street number and name."},"city":{"minLength":1,"maxLength":100,"type":"string","description":"City name"},"state":{"minLength":1,"maxLength":20,"type":"string","description":"State. Must be a 2 letter state code for US states."},"postalCode":{"minLength":1,"maxLength":10,"type":"string","description":"Postal code. Must be a 5 digit zip code for the United States."},"country":{"minLength":1,"maxLength":2,"type":"string","description":"ISO 2 character country code."},"email":{"minLength":1,"maxLength":100,"type":"string","description":"Valid email address of brand support contact."},"stockSymbol":{"maxLength":10,"type":"string","description":"Stock symbol. Required for entityType PUBLIC."},"stockExchange":{"$ref":"#/components/schemas/BrandStockExchange"},"website":{"minLength":1,"maxLength":100,"type":"string","description":"Brand website URL."},"vertical":{"maxLength":50,"type":"string","description":"Vertical or industry segment of the brand."},"altBusinessId":{"maxLength":50,"type":"string","description":"Alternate business identifier."},"altBusinessIdType":{"$ref":"#/components/schemas/BrandAltBusinessIdType"},"businessContactEmail":{"description":"Business contact email.","oneOf":[{"type":"string","format":"email"},{"type":"string","minLength":0,"maxLength":0}]}},"required":["country","displayName","email","entityType","phone","street","city","state","postalCode","companyName","ein","einIssuingCountry","website"]},"BrandEntityType":{"type":"string","description":"Legal entity type. It can't be updated when the brand is approved.","enum":["PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT",""]},"BrandStockExchange":{"type":"string","description":"Stock exchange. Required for entityType PUBLIC.","enum":["NONE","NASDAQ","NYSE","AMEX","AMX","ASX","B3","BME","BSE","FRA","ICEX","JPX","JSE","KRX","LON","NSE","OMX","SEHK","SGX","SSE","STO","SWX","SZSE","TSX","TWSE","VSE","OTHER",""]},"BrandAltBusinessIdType":{"type":"string","description":"Alternate business identifier type. Required if altBusinessId is provided.","enum":["NONE","DUNS","GIIN","LEI",""]},"WorkspaceTCRBrand":{"type":"object","additionalProperties":false,"required":["country","displayName","email","entityType","phone","street","city","state","postalCode","companyName","ein","einIssuingCountry","website"],"properties":{"id":{"type":"string","description":"The ID of the number.","format":"uuid"},"tcrBrandId":{"type":"string","description":"The Campaign Registry brand ID."},"organizationId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","description":"Timestamp (UTC) when the brand was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the brand was last updated.","nullable":true,"format":"date-time"},"status":{"$ref":"#/components/schemas/BrandStatus"},"authPlusStatus":{"$ref":"#/components/schemas/BrandAuthPlusStatus"},"entityType":{"$ref":"#/components/schemas/BrandEntityType"},"firstName":{"maxLength":100,"type":"string","description":"First or given name. Applicable to entity type."},"lastName":{"maxLength":100,"type":"string","description":"Last or Surname. Applicable to entity type."},"displayName":{"maxLength":255,"type":"string","description":"Display or marketing name your brand."},"companyName":{"maxLength":255,"type":"string","description":"Legal company name. This should match the legal company name used to register your EIN/Tax ID."},"ein":{"maxLength":21,"type":"string","description":"Government assigned corporate tax ID. EIN is 9-digits in the U.S."},"einIssuingCountry":{"maxLength":2,"type":"string","description":"The 2 letter ISO country of registration submitted with your EIN / Tax ID registration."},"phone":{"maxLength":20,"type":"string","description":"Valid phone number in e.164 international format."},"street":{"maxLength":100,"type":"string","description":"Street number and name."},"city":{"maxLength":100,"type":"string","description":"City name"},"state":{"maxLength":20,"type":"string","description":"State. Must be a 2 letter state code for US states."},"postalCode":{"maxLength":10,"type":"string","description":"Postal code. Must be a 5 digit zip code for the United States."},"country":{"maxLength":2,"type":"string","description":"ISO 2 character country code."},"email":{"maxLength":100,"type":"string","description":"Valid email address of brand support contact."},"stockSymbol":{"maxLength":10,"type":"string","description":"Stock symbol."},"stockExchange":{"$ref":"#/components/schemas/BrandStockExchange"},"website":{"maxLength":100,"type":"string","description":"Brand website URL."},"vertical":{"maxLength":50,"type":"string","description":"Vertical or industry segment of the brand."},"altBusinessId":{"maxLength":50,"type":"string","description":"Alternate business identifier."},"altBusinessIdType":{"$ref":"#/components/schemas/BrandAltBusinessIdType"},"businessContactEmail":{"description":"Business contact email.","oneOf":[{"type":"string","format":"email"},{"type":"string","minLength":0,"maxLength":0}]},"businessContactEmailVerifiedDate":{"type":"string","description":"Timestamp (UTC) when the brand businessContactEmail was verified.","format":"date-time"},"rejection":{"type":"object","description":"Rejection details","required":["description"],"properties":{"description":{"type":"string","description":"Rejection description"},"code":{"type":"string","description":"Rejection code"}}}}},"BrandStatus":{"type":"string","description":"Brand status","enum":["FAILED","PENDING","REJECTED","APPROVED","DELETED","DRAFT"]},"BrandAuthPlusStatus":{"type":"string","description":"Brand Auth+ status","enum":["NOT_APPLICABLE","NEEDS_CHARGE","NEEDS_TRIGGER","DONE"]},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tcr-brands":{"post":{"description":"Create a brand at workspace level. This means it will be available only for this workspace. A brand registration is mandatory due to compliance requirements.\n","operationId":"createWorkspaceBrand","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceTCRBrand"}}},"description":"Brand successfully created"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid brand"}},"summary":"Create a brand at workspace level","tags":["number_brands"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will create a new brand that will be submitted for registration with the campaign registry. 
curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/tcr-brands' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "entityType": "",
  "firstName": "",
  "lastName": "",
  "displayName": "",
  "companyName": "",
  "ein": "",
  "einIssuingCountry": "",
  "phone": "",
  "street": "",
  "city": "",
  "state": "",
  "postalCode": "",
  "country": "",
  "email": "",
  "stockSymbol": "",
  "stockExchange": "",
  "website": "",
  "vertical": "",
  "altBusinessId": "",
  "altBusinessIdType": ""
}
{% endtab %} {% endtabs %} ## (Optional) Submit brand for external vetting {% hint style="info" %} **A-Sync** : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result . {% endhint %} The final result of If your brand is not being accepted or your company is not part of the Russell 3000 stock index you can also request additional vetting. For brands that are not part of the Russell 3000 stock index this can provide access to higher messaging throughputs (depending on your vetting score) {% hint style="warning" %} A successful request to this endpoint will mean you are charged a [brand vetting](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/brand-registration#brand-registration-fees) fee. {% endhint %} ## Create a brand vetting at workspace level. > Create a brand vetting in a workspace. Brand vetting should be requested when the brand is not getting approved, or if the customer needs a higher throughput.
```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"TCR Brands","name":"number_brands"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateBrandVetting":{"type":"object","additionalProperties":false,"properties":{"class":{"$ref":"#/components/schemas/BrandVettingClass"},"vettingProviderId":{"type":"string","description":"External vetting provider ID for the brand."}},"required":["class"]},"BrandVettingClass":{"type":"string","description":"Identifies the vetting classification.","enum":["STANDARD"]},"BrandVetting":{"type":"object","additionalProperties":false,"required":["id","brandId","createdAt","status","vettingProviderId","score","class"],"properties":{"id":{"type":"string","description":"Unique ID that identifies a vetting transaction performed by a vetting provider.","format":"uuid"},"brandId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","description":"Vetting submission date (UTC). This is the date when the vetting request is generated","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the brand vetting was last updated.","nullable":true,"format":"date-time"},"status":{"$ref":"#/components/schemas/BrandVettingStatus"},"vettingProviderId":{"type":"string","description":"External vetting provider ID for the Brand vetting."},"token":{"type":"string"},"score":{"description":"Brand vetting score (0-100). Higher is better.","type":"string"},"class":{"$ref":"#/components/schemas/BrandVettingClass"},"reasons":{"type":"array","description":"A list of reasons for FAILED vetting.","items":{"type":"string"}}}},"BrandVettingStatus":{"type":"string","description":"Identifies the vetting request status.","enum":["PENDING","REJECTED","FAILED","APPROVED","EXPIRED"]},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tcr-brands/{brandId}/vettings":{"post":{"description":"Create a brand vetting in a workspace. Brand vetting should be requested when the brand is not getting approved, or if the customer needs a higher throughput.\n","operationId":"createWorkspaceBrandVetting","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrandVetting"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandVetting"}}},"description":"Brand vetting successfully created"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid workspace brand vetting"}},"summary":"Create a brand vetting at workspace level.","tags":["number_brands"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will create a new brand vetting request that will be submitted for registration with the campaign registry. You must have previously created a brand ```bash curl --location 'https://api.bird.com/workspaces//tcr-brands//vettings' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "class": "STANDARD", "vettingProviderId": "AEGIS" } ``` {% endtab %} {% endtabs %} ## Register a new campaign with the campaign registry {% hint style="danger" %} To reduce the likelihood of rejection, ensure you are familiar with 10dlc registration examples and best practices. Specifically * Check [this article ](https://docs.bird.com/applications/channels/channels/supported-channels/sms/concepts/sms-registration/use-case-requirements-for-sms-registration)for tips on how to write an effective Campaign `description` * Check [this article](https://docs.bird.com/applications/channels/channels/supported-channels/sms/concepts/sms-registration/setting-up-a-consent-gathering-flow) on how to write an effective `messageFlow` Most 10DLC rejections are caused by unclear or incomplete `description and/or messageFlow` {% endhint %} {% hint style="info" %} **A-Sync** : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result . {% endhint %} Once your brand status is approved you can then create your first [campaign](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/campaign-registration). Brands can have multiple campaigns. A campaign describes what types of messages you will send from your SMS channel. {% hint style="warning" %} Handling Attachments You will need to attach proof of opt-in and/or consent collection. To facilitate troubleshooting by both your team and the Bird team, we strongly recommend including a URL (e.g., to a third-party hosting service like Google Drive) directly in the `messageFlow` JSON field. **Note**: The `attachment` vector is only supported via the UI and is **not** currently supported via API POST requests. {% endhint %} ### Optional: acting as Reseller If you are registering a 10DLC campaign on behalf of third parties (e.g., your clients), you are required to also include your own contact information as part of the registration process. You can do so by including a `resellerId` in your POST campaign calls {% hint style="info" %} The Reseller ID is a unique value to be shared by all workspaces, all brands, and all campaigns created under your Organization. * If you operate as a reseller you only need to obtain a reseller UUID once and reuse it in all your requests * If you intend to register one or more brands (for example multiple branches of your company) for your internal use you can NULL the field {% endhint %} You can create and manage your Reseller information via the UI when creating a campaign
you can retrieve information via the following method {% hint style="warning" %} Ensure your reseller status is active before creating a campaign with it {% endhint %} ## GET /workspaces/{workspaceId}/tcr-resellers > List resellers in a workspace ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"TCR Resellers","name":"number_resellers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryLimit":{"description":"Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.\n","in":"query","name":"limit","schema":{"default":10,"maximum":99,"minimum":1,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryDirection":{"description":"Order in which to retrieve the results. By default, the orders are in ascending order date. To get the results in descending order, set this parameter to true.","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}}},"schemas":{"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.","type":"string"}},"type":"object"},"WorkspaceTCRReseller":{"type":"object","additionalProperties":false,"required":["email","phone","companyName"],"properties":{"id":{"type":"string","description":"UUID of the reseller.","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ResellerStatus"},"companyName":{"maxLength":255,"type":"string","description":"Legal company name. This should match the legal company name used to register your EIN/Tax ID."},"phone":{"maxLength":20,"type":"string","description":"Valid phone number in e.164 international format."},"email":{"maxLength":100,"type":"string","description":"Valid email address of support contact."},"createdAt":{"type":"string","description":"Timestamp (UTC) when the reseller was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the reseller was last updated.","format":"date-time"}}},"ResellerStatus":{"type":"string","description":"Reseller status","enum":["FAILED","PENDING","ACTIVE","DELETED"]}}},"paths":{"/workspaces/{workspaceId}/tcr-resellers":{"get":{"operationId":"listWorkspaceResellers","parameters":[{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryDirection"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/pagination"},{"properties":{"results":{"items":{"$ref":"#/components/schemas/WorkspaceTCRReseller"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"OK"}},"summary":"List resellers in a workspace","tags":["number_resellers"]}}}} ``` ### Creating a New Campaign After creating a campaign, this will be submitted for approval by the campaign registry. The campaign must be approved before you can associate this with an SMS channel. Campaign registration can take 1-2 weeks to be approved. You can find the full list of campaign management endpoints [here](https://docs.bird.com/api/numbers-api/api-reference/10dlc-compliance) {% hint style="warning" %} A successful request to this endpoint will mean you are charged a [campaign registration fee](https://app.gitbook.com/s/U9kiDiTGVD8kkbnKKyEn/channels/channels/supported-channels/sms/concepts/united-states-sms-registration/sms-10dlc/campaign-registration#campaign-registration-and-subscription-fees) and a three month minimum commitment fee. If you later need to update or resubmit your brand there may be additional fees. {% endhint %} ## Create campaign. A campaign can only be created for an approved brand. > To create a campaign, it is essential to ensure that the brand has already been approved. Campaigns can only be initiated under the umbrella of brands that meet this prerequisite. Once a campaign is created, it cannot begin directing traffic immediately. Instead, it must go through a formal approval process. Only after the campaign has been reviewed and approved it will be authorized to send traffic.\ > \ > \*\*Attachments\*\*: You can include up to 5 file attachments (max 10MB each) by providing URLs in the \`attachmentUrls\` field. Both internal media service URLs and external URLs (e.g., Azure Blob Storage, AWS S3) are supported. External files are automatically downloaded and uploaded to the media service.
```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"TCR Campaigns","name":"number_campaigns"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateCampaign":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","description":"Campaign name"},"usecase":{"type":"string","maxLength":50,"description":"A use case that best matches the purpose of the campaign."},"subUsecases":{"type":"array","uniqueItems":true,"description":"If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases.","items":{"type":"string"}},"description":{"type":"string","maxLength":4096,"minLength":40,"description":"A detailed description of what the campaign is for."},"embeddedLink":{"type":"boolean","description":"Whether messages will contain links. Provide at least one sample containing a link."},"embeddedPhone":{"type":"boolean","description":"Whether messages will contain phone number. Provide at least one sample containing a phone number."},"numberPool":{"type":"boolean","description":"Whether a campaign will be associated with more than 50 numbers e.g. customer service use case."},"ageGated":{"type":"boolean","description":"Whether a campaign contains age-gated content based on carrier/ctia guidelines."},"directLending":{"type":"boolean","description":"Whether a campaign includes content related to direct lending or loan arrangements."},"subscriberOptin":{"type":"boolean","description":"Confirm customer opt in is collected and processed."},"subscriberOptout":{"type":"boolean","description":"Confirm customer opt out is collected and processed."},"subscriberHelp":{"type":"boolean","description":"Confirm an info message is returned if a customer sends \"HELP\"."},"samples":{"type":"array","description":"Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples.","items":{"type":"string","minItems":1,"maxItems":5}},"attachmentUrls":{"type":"array","description":"Up to 5 attachment URLs (max 10MB each). Supports both internal media service URLs and external URLs.\n\n**Internal URLs**: Obtained via `POST /workspaces/{workspaceId}/tcr-brands/{brandId}/pre-signed-upload`\n\n**External URLs**: Any publicly accessible HTTPS URL (e.g., Azure Blob Storage, AWS S3). External files are automatically downloaded and uploaded to the media service.\n\nExamples:\n- `https://channels.messagebird.com/v1/media/temp/abc123` (internal)\n- `https://mybucket.blob.core.windows.net/files/consent.pdf?signature=...` (external)\n","uniqueItems":true,"items":{"type":"string","maxItems":5}},"messageFlow":{"type":"string","maxLength":2048,"minLength":40,"description":"Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out."},"helpMessage":{"type":"string","maxLength":255,"minLength":20,"description":"Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords."},"helpKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info."},"optoutKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT."},"optinKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT."},"optinMessage":{"type":"string","minLength":20,"description":"Provide an example of the message that will be sent after a customer has opted in."},"optoutMessage":{"type":"string","minLength":20,"description":"Provide an example of the message that will be sent after a customer has opted out."},"termsAndConditions":{"type":"boolean","enum":[true],"description":"Indicates the campaign follows CTIA messaging principles and best practices."},"resellerId":{"type":"string","format":"uuid","description":"UUID of the reseller associated with this campaign. The specified reseller MUST be ACTIVE.","nullable":true}},"required":["name","usecase","description","samples","messageFlow","helpMessage","termsAndConditions"]},"Campaign":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"UUID of the campaign.","format":"uuid"},"name":{"type":"string","description":"Campaign name"},"subscription":{"$ref":"#/components/schemas/CampaignSubscription"},"status":{"type":"string","description":"Campaign status","enum":["DRAFT","FAILED","PENDING","REJECTED","APPROVED","DECLINED","SUSPENDED","DELETED","EXPIRED"]},"usecase":{"type":"string","description":"A use case that best matches the purpose of the campaign."},"subUsecases":{"type":"array","description":"If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases.","items":{"type":"string"},"nullable":true},"description":{"type":"string","description":"A detailed description of what the campaign is for."},"embeddedLink":{"type":"boolean","description":"Whether messages will contain links. Provide at least one sample containing a link."},"embeddedPhone":{"type":"boolean","description":"Whether messages will contain phone number. Provide at least one sample containing a phone number."},"numberPool":{"type":"boolean","description":"Whether a campaign will be associated with more than 50 numbers e.g. customer service use case."},"ageGated":{"type":"boolean","description":"Whether a campaign contains age-gated content based on carrier/ctia guidelines."},"directLending":{"type":"boolean","description":"Whether a campaign includes content related to direct lending or loan arrangements."},"subscriberOptin":{"type":"boolean","description":"Confirm customer opt in is collected and processed."},"subscriberOptout":{"type":"boolean","description":"Confirm customer opt out is collected and processed."},"subscriberHelp":{"type":"boolean","description":"Confirm an info message is returned if a customer sends \"HELP\"."},"samples":{"type":"array","description":"Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples.","items":{"type":"string","minItems":1,"maxItems":5}},"messageFlow":{"type":"string","description":"Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out."},"helpMessage":{"type":"string","description":"Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords."},"helpKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info."},"optoutKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT."},"optinKeywords":{"type":"string","description":"A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT."},"optinMessage":{"type":"string","description":"Provide an example of the message that will be sent after a customer has opted in."},"optoutMessage":{"type":"string","description":"Provide an example of the message that will be sent after a customer has opted out."},"termsAndConditions":{"type":"boolean","description":"Indicates the campaign follows CTIA messaging principles and best practices."},"brandId":{"type":"string","description":"UUID of the brand associated with this campaign. The specified brand MUST be APPROVED.","format":"uuid"},"resellerId":{"type":"string","description":"UUID of the reseller associated with this campaign. The specified reseller MUST be ACTIVE.","nullable":true},"rejection":{"type":"object","description":"Rejection details","required":["description"],"properties":{"description":{"type":"string","description":"Rejection description"},"code":{"type":"string","description":"Rejection code"}}},"attachments":{"type":"array","description":"Attachments associated with this campaign.","items":{"$ref":"#/components/schemas/Attachment"}},"createdAt":{"type":"string","description":"Timestamp (UTC) when the campaign was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the campaign was last updated.","format":"date-time"}}},"CampaignSubscription":{"type":"object","title":"CampaignSubscription","additionalProperties":false,"description":"Describes status of Campaign Subscription","nullable":true,"properties":{"status":{"type":"string","enum":["active","inactive","canceling"]},"subscribedAt":{"type":"string","description":"Timestamp (UTC) when the subscription became active.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the subscription was last updated.","nullable":true,"format":"date-time"},"cancelledAt":{"type":"string","description":"Timestamp (UTC) when the subscription was cancelled.","nullable":true,"format":"date-time"}}},"Attachment":{"type":"object","additionalProperties":false,"required":["id","status","filename","contentType","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"The ID of the attachment.","format":"uuid"},"status":{"$ref":"#/components/schemas/AttachmentStatus"},"createdAt":{"type":"string","description":"Timestamp (UTC) when the attachment was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the attachment was last updated.","nullable":true,"format":"date-time"},"filename":{"type":"string","description":"The original name of the file when it was uploaded."},"mediaUrl":{"type":"string","description":"The URL to download the attachment."},"contentType":{"type":"string","description":"The detected MIME type of the file."}}},"AttachmentStatus":{"type":"string","description":"Attachment status","enum":["PENDING","ACTIVE","PENDING_DELETION","DELETED","FAILED","FAILED_DELETION"]},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tcr-brands/{brandId}/campaigns":{"post":{"description":"To create a campaign, it is essential to ensure that the brand has already been approved. Campaigns can only be initiated under the umbrella of brands that meet this prerequisite. Once a campaign is created, it cannot begin directing traffic immediately. Instead, it must go through a formal approval process. Only after the campaign has been reviewed and approved it will be authorized to send traffic.\n\n**Attachments**: You can include up to 5 file attachments (max 10MB each) by providing URLs in the `attachmentUrls` field. Both internal media service URLs and external URLs (e.g., Azure Blob Storage, AWS S3) are supported. External files are automatically downloaded and uploaded to the media service.\n","operationId":"createTCRCampaign","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaign"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Campaign successfully created"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid campaign"}},"summary":"Create campaign. A campaign can only be created for an approved brand.","tags":["number_campaigns"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will create a new campaign that will be submitted for registration with the campaign registry. Your associated brand must be approved {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//tcr-brands//campaigns' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "name": "", "usecase": "", "subUsecases": [ "" ], "description": "", "embeddedLink": , "embeddedPhone": , "numberPool": , "ageGated": , "directLending": , "subscriberOptin": , "subscriberOptout": , "subscriberHelp": , "samples": [ "" ], "messageFlow": "", "helpMessage": "", "helpKeywords": "", "optoutKeywords": "", "optinKeywords": "", "optinMessage": "", "optoutMessage": "", "termsAndConditions": true }' ``` {% endcode %} {% endtab %} {% endtabs %} ## (Optional) create a workspace subscription to list to channel related events Same as done before, you can create a workspace subscription to listen to Channel Status changes #### Channel Updates Subscription The example below will create a workspace-wide subscription tracking all updates regarding your channels you can use to track channels' status changes ``` curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "service": "channels", "event": "channel.updated", "url": "myURL.com", "signingKey": "mysecretkey", "eventFilters": [ ] }' ``` ## Install a channel connector {% hint style="info" %} **A-Sync** : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result . {% endhint %} ## POST /workspaces/{workspaceId}/connectors > Create a new connector from a template. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateConnectorReq":{"type":"object","title":"A request to instantiate a new connector from a template","additionalProperties":false,"properties":{"name":{"type":"string","title":"connector name"},"connectorTemplateRef":{"type":"string","title":"template to base this connector on by ref"},"arguments":{"title":"arguments to provide to each action invocation on this connector","$ref":"#/components/schemas/ConnectorArguments"},"securityArguments":{"$ref":"#/components/schemas/SecurityArgumentsMap"},"channelConversationalStatusEnabled":{"title":"Controls the default value for channel's conversational flag.","type":"boolean","nullable":true},"invitationToken":{"title":"Invitation token to allow installation of connectors that are not GA.","type":"string","nullable":true}},"required":["name"]},"ConnectorArguments":{"type":"object","title":"ConnectorArguments","description":"For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.","additionalProperties":true,"nullable":true},"SecurityArgumentsMap":{"type":"object","title":"SecurityArgumentsMap","description":"Provide the arguments required by the security scheme(s) on the connector template.","additionalProperties":{"type":"object","title":"SecurityArguments","additionalProperties":{"type":"string"}},"nullable":true},"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors":{"post":{"operationId":"createConnector","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectorReq"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"workspace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector already exists"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid data provided"}},"summary":"Create a new connector from a template.","tags":["Connectors"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will create a new SMS connector with an approved 10DLC campaign and US local number: {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//connectors' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "connectorTemplateRef": "sms-messagebird:1", "name": "SMS channel", "arguments": { "phoneNumberId": "", "useCaseId": "", "channelMessageType": "", }, "channelConversationalStatusEnabled": true } ``` {% endcode %} {% endtab %} {% tab title="Arguments" %} | Property | Type | Description | Required | | ---------------------------------- | ------- | ---------------------------------------------------------------- | -------- | | connectorTemplateRef | string | Set as **sms-messagebird:1** | Yes | | name | string | The name of your connector e.g. My SMS channel | Yes | | arguments.phoneNumberId | string | The ID of the number you created above | Yes | | arguments.channelMessageType | string | The type of traffic that will be sent through this channel | Yes | | arguments.useCaseId | string | The ID of your campaign | Yes | | channelConversationalStatusEnabled | boolean | If true incoming messages will create new conversations in Inbox | No | {% endtab %} {% endtabs %} ## Get your channel id Once you have created your SMS connector, this will create an SMS channel. You can then get your channel ID to before setting up channel webhooks {% hint style="info" %} If you are listening to channels events the `channelId` will be returned with the first channel updated event {% endhint %} ## GET /workspaces/{workspaceId}/connectors/{connectorId} > Show the details of a specific connector. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}":{"get":{"operationId":"getConnector","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector not found"}},"summary":"Show the details of a specific connector.","tags":["Connectors"]}}}} ``` {% tabs %} {% tab title="Request" %} The following example will get the connector you have created in the previous step. Parse the `channel.channelId` to get the id of your new SMS channel {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//connectors/' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' ``` {% endcode %} {% endtab %} {% endtabs %} ## Setup channel message webhooks Once your channel has been installed you will then need to setup a webhook subscription to receive status updates and inbound messages ## Create a webhook subscription > To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\ > You can create multiple webhook subscriptions to route different types of events to various URLs as needed.\ > Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\ > If you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.
```json {"openapi":"3.0.3","info":{"title":"Notifications","version":"1.0.0"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWebhookSubscription":{"allOf":[{"type":"object","required":["service","event","url"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/WebhookEventFilter"},"description":"Filters to apply to the events that are sent to the webhook. This is a key-value list of filters that are specific to the service that the webhook is subscribed to.\nOne example would be a key of `channelId` and a value of a UUID (in string format) that represents a channel.\n"},"template":{"type":"string"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"}},"oneOf":[{"$ref":"#/components/schemas/EventFiltersChannels"},{"$ref":"#/components/schemas/EventFiltersNumbers"},{"$ref":"#/components/schemas/EventFiltersPayments"},{"$ref":"#/components/schemas/EventFiltersConversations"},{"$ref":"#/components/schemas/EventFiltersTemplates"}],"discriminator":{"propertyName":"service","mapping":{"channels":"#/components/schemas/EventFiltersChannels","numbers":"#/components/schemas/EventFiltersNumbers","payments":"#/components/schemas/EventFiltersPayments","conversations":"#/components/schemas/EventFiltersConversations","templates":"#/components/schemas/EventFiltersTemplates"}}}]},"WebhookService":{"type":"string","enum":["channels","numbers","payments","conversations","templates"],"description":"The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be `channels`.\n"},"WebhookEvent":{"type":"string","description":"The event name identifies the webhook event, such as `sms.outbound` for notifications about SMS messages being sent.\n"},"WebhookEventFilter":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId","platformId","channelStatus","interactionType","messageStatus","status","eventDestination","navigatorId"]},"value":{"type":"string"}},"description":"Filters used to narrow down events sent to the webhook. For example, if you want to receive events for a specific platform,\na valid filterKey would be `platformId` with a value of `sms`.\n"},"Url":{"type":"string","pattern":"^https://([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(/[^\\s]*)?$","description":"The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that respects the established pattern and is accessible from the internet.\n"},"SigningKey":{"type":"string","description":"The signing key for the webhook and can be used to verify the authenticity of the webhook.\n"},"EventFiltersChannels":{"type":"object","title":"Channels service filters","properties":{"service":{"type":"string","enum":["channels"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}},{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["messageStatus","interactionType","channelStatus","platformId","status"]},"value":{"type":"string"}}}]}}}},"EventFiltersNumbers":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["numbers"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"description":"The numbers service does not have any specific filters for its events.\n","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersPayments":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["payments"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersConversations":{"type":"object","title":"Conversations service filters","properties":{"service":{"type":"string","enum":["conversations"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}}]}}}},"EventFiltersTemplates":{"type":"object","title":"Templates service filters","properties":{"service":{"type":"string","enum":["templates"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["platformId"]},"value":{"type":"string"}}}]}}}},"WebhookSubscription":{"type":"object","required":["id","organizationId","workspaceId","service","event","url","status"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.\n"},"organizationId":{"$ref":"#/components/schemas/WebhookOrganizationId"},"workspaceId":{"$ref":"#/components/schemas/WebhookWorkspaceId"},"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventFilter"}},"template":{"$ref":"#/components/schemas/Template"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"},"status":{"$ref":"#/components/schemas/WebhookSubscriptionStatus"},"statusReason":{"type":"string","description":"A human-readable explanation for the current status of the webhook subscription.\n"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookOrganizationId":{"type":"string","format":"uuid"},"WebhookWorkspaceId":{"type":"string","format":"uuid"},"Template":{"type":"string","description":"Used for our Exit APIs for Twilio and Sinch.\nMore information can be found [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api) for Twilio and [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/sinch-exit-api) for Sinch.\n"},"WebhookSubscriptionStatus":{"type":"string","enum":["active","inactive"]},"errorResponse":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions":{"post":{"summary":"Create a webhook subscription","description":"To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\nYou can create multiple webhook subscriptions to route different types of events to various URLs as needed.\nEvent filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\nIf you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.\n","operationId":"createLegacyWebhookSubscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscription"}}}},"responses":{"201":{"description":"The webhook subscription was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Invalid HTTP request. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}},"422":{"description":"The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}}} ``` {% tabs %} {% tab title="Request" %} The following request example will create a new SMS subscription for inbound and outbound messages **Inbound messages** {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "signingKey": "my-signing-key", "eventFilters": [ { "key": "channelId", "value": "" } ], "event": "sms.inbound", "service": "channels", "url": "" }' ``` {% endcode %} **Outbound messages** {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "signingKey": "my-signing-key", "eventFilters": [ { "key": "channelId", "value": "" } ], "event": "sms.outbound", "service": "channels", "url": "" }' ``` {% endcode %} {% endtab %} {% tab title="Arguments" %} | Property | Type | Description | Required | | ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | signingKey | string | Set your own signing key to validate webhooks | Yes | | event | string | The event you are subscribing to. For SMS channels either **sms.outbound** or **sms.inbound** | Yes | | event\[] | object | Event filters are inclusive, which means you will only get events for filters you add | No | | eventFilters.**key** | string | If you do not want events for all events you can add a filter. Eventfilters are inclusive e.g. for each event filter you add you will get those events. Valid filters for channels are **channelId** | No | | eventFilters.**value** | string | The filter value. In this case a channelid. You will get webhooks for this channel | No | | service | string | The service that will be sending the webhooks. In this case **channels** | | | url | string | A valid HTTPS endpoint to receive the webhooks | Yes | | {% endtab %} | | | | | {% endtabs %} | | | | ## Confirm a 10DLC Channels Readiness to send SMS traffic {% hint style="info" %} A-Sync : this will start a background process that may require some time to complete. A Get call may be required to retrieve the final result {% endhint %} 10DLC numbers can only send traffic to the USA when linked to a campaign. Number Campaign link is an A-sync process requiring confirmations from multiple carriers. {% hint style="warning" %} The bird will only consider a number linked if all major USA carriers acknowledge the links. Delays in carrier acknowledgment can vary between 15 minutes to several hours and are usually longer around peak linking hours (afternoon/evening USA Pacific time) {% endhint %} Based on whether you have subscribed or not to channel events, you can determine the readiness of a given channel in 2 ways #### Option 1: you are subscribed to channel updates if you have a `"channel.updated"` event subscription, each change in a channel status will trigger an event. You can associate those events to the number you have used to install the channel by referring to "`identifier"` field. A channel ready to send SMS will have `"status": "active"`. ``` { "service": "channels", "event": "channel.created", "payload": { "id": "f5d391a8-29b6-5092-940c-9a1cd7d06f30", "status": "active", "platformId": "sms-messagebird", "name": "SMS - 🇺🇸 +19802683122", "connectorId": "c8a93146-68e5-4e60-a77c-659877768bec", "identifier": "+19802683122", "preferences": { "disableProfileFetching": false, "explicitMarketingOptOut": false, "trackAdInitiatedThreads": false }, "capabilities": { "messaging": { "displayName": "Messaging capabilities", "status": "active", "name": "", "expiresAt": "1970-01-01T00:00:00Z", "version": 0, "createdAt": "0001-01-01T00:00:00Z", "updatedAt": "0001-01-01T00:00:00Z", "outgoing": { "displayName": "Capability to send outgoing messages", "status": "active", "name": "", "version": 0, "createdAt": "1970-01-01T00:00:00Z", "updatedAt": "1970-01-01T00:00:00Z", "mms": { "displayName": "Capability to send outgoing mms messages", "status": "inactive", "name": "", "version": 0, "createdAt": "1970-01-01T00:00:00Z", "updatedAt": "1970-01-01T00:00:00Z" } }, "incoming": { "displayName": "Capability to receive messages", "status": "active", "name": "", "version": 0, "createdAt": "1970-01-01T00:00:00Z", "updatedAt": "1970-01-01T00:00:00Z" } } }, "useCaseId": "b43d79ab-3cbb-4a4a-9461-5da533f0cb18", "useCaseType": "marketing", "createdAt": "2024-09-20T12:08:57.098Z", "updatedAt": "2024-09-20T12:08:57.098Z" } } ``` #### Option 2: you are NOT subscribed to channel updates if so you can query the [GET connector status endpoint ](https://docs.bird.com/api/api-reference/channel-connectors#check-the-readiness-of-a-connector-and-its-channel-to-send-sms) and wait for the "`useCaseStatus"` to turn to `"ok"` #### The channel cannot terminate SMS to the USA This could happen if the number linked to its campaigns is not acknowledged or the 10DLC registration experiences issues. In this case, the "`useCaseStatus"` 's value will not be "ok" ``` "name": "useCaseStatus", "displayName": "UseCase Status", "assertions": [ { "name": "brand", "displayName": "", "description": "", "status": "ok" }, { "name": "campaign", "displayName": "", "description": "", "status": "ok" }, { "name": "checks whether number is linked to campaign", "displayName": "", "description": "", "status": "warning", "message": "Number status is INACTIVE" } ], "status": "warning" ``` #### The channel can terminate messages to the USA In this case "`useCaseStatus"` will be `"ok"` ```` "name": "useCaseStatus", "displayName": "UseCase Status", "assertions": [ { "name": "brand", "displayName": "", "description": "", "status": "ok" }, { "name": "campaign", "displayName": "", "description": "", "status": "ok" }, { "name": "checks whether number is linked to campaign", "displayName": "", "description": "", "status": "ok" } ], "status": "ok" ``` ````