# Create a campaign {% 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="warning" %} A successful request to this endpoint will mean you are charged a [campaign registration fee](https://docs.bird.com/applications/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 %} {% hint style="info" %} * You must have created a brand that has been approved, before creating a new campaign * [If you operate as a Reseller](/api/numbers-api/api-reference/10dlc-compliance/campaigns/optional-acting-as-reseller.md) ensure your Reseller registration is active before using the reseller field in POST campaigns {% endhint %} {% 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 %} ### ## 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","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, each 20-1024 characters. If directLending, embeddedPhone, embeddedLink is true provide relevant examples.","minItems":1,"maxItems":5,"items":{"type":"string","minLength":20,"maxLength":1024}},"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":4096,"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, each up to 1024 characters (empty until the campaign is submitted). If directLending, embeddedPhone, embeddedLink is true provide relevant examples.","maxItems":5,"items":{"type":"string","maxLength":1024}},"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"]},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"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":{"$ref":"#/components/responses/error.response.invalid_request"}},"summary":"Create campaign. A campaign can only be created for an approved brand.","tags":["number_campaigns"]}}}} ``` ## CampaignRequest object
FieldTypeDescriptionMandatory
namestringName of your use caseRequired
useCaseuseCaseA use case that best matches the purpose of the campaignRequired
subUsecasesarray<useCase>If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use casesOptional. Unless useCase is LOW_VOLUME, MIXED
descriptionstringA detailed description of what the campaign is forRequired
embeddedLinkbooleanWhether messages will contain links. Provide at least one sample containing a linkRequired
embeddedPhonebooleanWhether messages will contain phone number. Provide at least one sample containing a phone numberRequired
numberPoolbooleanWhether a campaign will be associated with more than 50 numbers e.g. customer service use caseRequired
ageGatedbooleanWhether a campaign contains age-gated content based on carrier/ctia guidelinesRequired
directLendingbooleanWhether a campaign includes content related to direct lending or loan arrangementsRequired
subscriberOptinbooleanConfirm customer opt in is collected and processedRequired
subscriberOptoutbooleanConfirm customer opt out is collected and processedRequired
subscriberHelpbooleanConfirm an info message is returned if a customer sends “HELP”Required
samplesarray<string>Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examplesRequired. At least 1 sample
messageFlowstringProvide 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 outRequired
helpKeywordsstringA comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info.Required
optoutKeywordsstringA comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT.Required
optInKeywordsstringA comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT.Optional. Required if subscriberOptin is true
helpMessagestringHelp 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.Required
optinMessagestring
Provide an example of the message that will be sent after a customer has opted in.		Optional. Required if subscriberOptin is true
optoutMessagestingProvide an example of the message that will be sent after a customer has opted out.Required
termsAndConditionsbooleanIndicates the campaign follows CTIA messaging principles and best practicesRequired
## CampaignResponse object | Field | Type | Description | | ------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | useCase | [useCase](/api/numbers-api/api-reference/10dlc-compliance/tcr-enums.md#usecases) | A use case that best matches the purpose of the campaign | | subUsecases | array<[useCase](/api/numbers-api/api-reference/10dlc-compliance/tcr-enums.md#usecases)> | If use case is MIXED or LOW\_VOLUME mixed an array of 2-5 use cases | | description | string | A detailed description of what the campaign is for | | embeddedLink | boolean | Whether messages will contain links. Provide at least one sample containing a link | | embeddedPhone | boolean | Whether messages will contain phone number. Provide at least one sample containing a phone number | | numberPool | boolean | Whether a campaign will be associated with more than 50 numbers e.g. customer service use case | | ageGated | boolean | Whether a campaign contains age-gated content based on carrier/ctia guidelines | | directLending | boolean | Whether a campaign includes content related to direct lending or loan arrangements | | subscriberOptin | boolean | Confirm customer opt in is collected and processed | | subscriberOptout | boolean | Confirm customer opt out is collected and processed | | subscriberHelp | boolean | Confirm an info message is returned if a customer sends “HELP” | | samples | array\ | Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples | | messageFlow | string | 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 | | helpKeywords | string | A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info. | | optoutKeywords | string | A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT. | | optInKeywords | string | A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT. | | helpMessage | string | 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. | | optinMessage | string |


| | optoutMessage | sting | Provide an example of the message that will be sent after a customer has opted in. | | termsAndConditions | boolean | Indicates the campaign follows CTIA messaging principles and best practices | | brandId | string | Alphanumeric identifier of the brand associated with this campaign. The specified brand MUST be APPROVED. | | campaignId | string | Alphanumeric identifier of the campaign | | campaignStatus | [campaignStatus](/api/numbers-api/api-reference/10dlc-compliance/tcr-enums.md#campaignstatus) | Campaign status | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/numbers-api/api-reference/10dlc-compliance/campaigns/create-a-campaign.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.