To register a brand, follow these steps:
All API endpoints described below require authentication. You can authenticate your requests using one of the following two methods for the Authorization header:
Bearer Token:
Authorization: Bearer <YourJwtToken>Basic Authentication:
Authorization: Basic <YourBase64EncodedCredentials>This endpoint returns the template of required information for creating or updating a brand. Think of it as a blueprint for the data payload you will send to both the CreateAndSubmitBrand and UpdateBrand endpoints.
Use this endpoint to find out:
- Which fields are required for submission.
- The correct name to use for each field.
- All validation rules, such as character limits, required formats, and accepted values.
The following curl command demonstrates how to retrieve the metadata for a given brand ID:
Request
curl --location 'https://brands-api.numbers-registration.staging.sinch.com/v1/projects/27eb83b8-6030-491b-a3f5-2fc4b92a3aee/brand-metadata?brandType=US_SHORT_CODE_REGISTRY' \
--header 'Authorization: ......'Response
{
"brandMetadataId": "e442df25-e1fb-4651-b841-aca1073cf978",
"brandType": "US_SHORT_CODE_REGISTRY",
"marketCode": "US",
"majorVersion": 2,
"minorVersion": 0,
"createTime": "2025-10-09T14:05:44.863006Z",
"data": [
{
"attributes": [
{
"example": "E.g. Tech Innovators LLC",
"minLength": 1,
"name": "name",
"required": true,
"title": "Legal company name",
"type": "string"
},
{
"example": "E.g. Tech Solutions",
"maxLength": 80,
"name": "dba",
"required": false,
"title": "Doing business as",
"type": "string"
},
{
"enum": [
"Corporation",
"Limited Liability Corporation (LLC)",
"Partnership",
"S Corporation",
"Sole Proprietorship"
],
"name": "legal_entity_type",
"required": true,
"title": "Entity type",
"type": "string"
},
{
"example": "E.g. AAPL",
"maxLength": 5,
"name": "symbol",
"required": false,
"title": "Stock market symbol",
"type": "string"
},
{
"example": "E.g. www.techinnovators.com",
"messages": {
"minLength": "At least 1 character is required",
"pattern": "Needs to be a valid URL address"
},
"minLength": 1,
"name": "url",
"pattern": "^(http://www.|https://www.|http://|https://)?[a-z0-9]+([-.]{1}[a-z0-9]+)*.[a-z]{2,63}(:[0-9]{1,5})?(/.*)?$",
"required": true,
"title": "Website URL",
"type": "string"
}
],
"categoryType": "GENERAL",
"title": "Company information"
},
{
"attributes": [
{
"enum": [
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"AO",
"AQ",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BY",
"BZ",
"CA",
"CC",
"CD",
"CF",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CU",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HT",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IR",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KP",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"LY",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"ML",
"MM",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NI",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RU",
"RW",
"SA",
"SB",
"SC",
"SD",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SO",
"SR",
"SS",
"ST",
"SV",
"SX",
"SY",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VE",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"YE",
"YT",
"ZA",
"ZM",
"ZW"
],
"name": "country",
"required": true,
"title": "Country",
"type": "string"
},
{
"example": "E.g. 123 Innovation Street",
"minLength": 1,
"name": "street",
"required": true,
"title": "Street address",
"type": "string"
},
{
"example": "E.g. Suite 500",
"minLength": 1,
"name": "street2",
"required": false,
"title": "Street address 2",
"type": "string"
},
{
"example": "E.g. Chicago",
"minLength": 1,
"name": "city",
"required": true,
"title": "City",
"type": "string"
},
{
"example": "E.g. Illinois",
"minLength": 1,
"name": "state",
"required": true,
"title": "State",
"type": "string"
},
{
"description": "2 characters",
"example": "E.g. IL",
"maxLength": 2,
"minLength": 2,
"name": "state_code",
"required": true,
"title": "State code",
"type": "string"
},
{
"minLength": 5,
"name": "zip",
"required": true,
"title": "Zip / Postal Code",
"type": "string"
}
],
"categoryType": "BRAND_CLIENT_ADDRESS",
"title": "Address Information"
},
{
"attributes": [
{
"description": "9 digits",
"maxLength": 9,
"minLength": 9,
"name": "federal_tax_id",
"required": true,
"title": "Federal Tax ID (EIN)",
"type": "string"
},
{
"description": "9 digits",
"maxLength": 9,
"minLength": 9,
"name": "duns",
"required": false,
"title": "Dun and Bradstreet (DUNS)",
"type": "string"
},
{
"description": "20 characters",
"maxLength": 20,
"minLength": 20,
"name": "giin",
"required": false,
"title": "GIIN",
"type": "string"
},
{
"description": "20 characters",
"maxLength": 20,
"minLength": 20,
"name": "lei",
"required": false,
"title": "Legal Entity Identifier (LEI)",
"type": "string"
}
],
"categoryType": "BUSINESS_IDENTIFIER",
"title": "Business identifiers"
},
{
"attributes": [
{
"minLength": 1,
"name": "first_name",
"required": true,
"title": "First name",
"type": "string"
},
{
"minLength": 1,
"name": "last_name",
"required": true,
"title": "Last name",
"type": "string"
},
{
"messages": {
"minLength": "At least 6 digits are required",
"pattern": "The number needs to start with the country code prefix and must have at least 6 digits. For example +46999444444 or 0046999444444"
},
"name": "phone",
"pattern": "^(?:\\+|00)\\d{6,}$",
"required": true,
"title": "Phone number",
"type": "string"
},
{
"example": "E.g. 1234",
"maxLength": 6,
"name": "phone_extension",
"required": false,
"title": "Phone extension",
"type": "string"
},
{
"description": "Public domains not allowed",
"example": "E.g. john.doe@yourcompany.com",
"messages": {
"minLength": "At least 1 character is required",
"pattern": "Needs to be a valid email address"
},
"name": "email",
"pattern": "^\\S+@\\S+\\.\\S+$",
"required": true,
"title": "Email",
"type": "string"
}
],
"categoryType": "BRAND_CLIENT_POINT_OF_CONTACT",
"title": "Contact Information"
},
{
"attributes": [
{
"description": "If you want to request a vanity Short Code, please specify your preference",
"example": "21234",
"maxLength": 10,
"minLength": 3,
"name": "vanity_sc",
"required": false,
"title": "Vanity Short Code",
"type": "string"
},
{
"description": "In case that you selected a Vanity Short Code and the selected code is not available, please select an alternative code",
"example": "20666",
"maxLength": 10,
"minLength": 3,
"name": "vanity_alt_sc",
"required": false,
"title": "Alternative Vanity Short Code",
"type": "string"
}
],
"categoryType": "SHORTCODE",
"title": "Short Code Information"
}
]
}This endpoint allows for the creation and submission of a new brand in a single API call.
It requires a brand_name and a brand_metadata_id. The structure of the data payload is dynamic and must conform to the specific requirements and fields defined by the chosen brand_metadata_id.
The following curl command demonstrates how to create and submit new brand using metadata's brand ID:
Request
curl --location 'https://brands-api.numbers-registration.staging.sinch.com/v1/projects/27eb83b8-6030-491b-a3f5-2fc4b92a3aee/brands:submit' \
--header 'Content-Type: text/plain' \
--header 'Authorization: ......' \
--data-raw '{
"brandName": "My New Brand",
"brandMetadataId": "e442df25-e1fb-4651-b841-aca1073cf976",
"data": [
{
"legal_entity_type": "Corporation",
"name": "Abc Store Corp.",
"symbol": "SNC",
"url": "https://abc-store.net"
},
{
"city": "Miami",
"country": "US",
"state": "Florida",
"state_code": "FL",
"street": "1450 SW 22nd St",
"zip": "33145"
},
{
"federal_tax_id": "234342344"
},
{
"email": "contactabcsinch.com",
"first_name": "Abc",
"last_name": "Sinch",
"phone": "+13054454855"
}
],
"callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49"
}'Response
{
"brandId": "01k7h5y64mh4fwcmxxa48h9m75",
"brandName": "My New Brand",
"brandMetadataId": "e442df25-e1fb-4651-b841-aca1073cf976",
"status": "NEW",
"data": [
{
"legal_entity_type": "Corporation",
"name": "Abc Store Corp.",
"symbol": "SNC",
"url": "https://abc-store.net"
},
{
"city": "Miami",
"country": "US",
"state": "Florida",
"state_code": "FL",
"street": "1450 SW 22nd St",
"zip": "33145"
},
{
"federal_tax_id": "234342344"
},
{
"email": "contact@abcsinch.com",
"first_name": "Abc",
"last_name": "sinch",
"phone": "+13054454855"
}
],
"logs": [
{
"status": "NEW",
"comment": "",
"author": "AGENT",
"createTime": "2025-10-14T10:58:27.111076"
}
],
"callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49",
"createTime": "2025-10-14T10:58:27.095235",
"updateTime": "2025-10-14T10:58:27.095235"
}This endpoint allows you to modify the details of an existing brand.
To use it, you must specify which brand to update by including its brandId in the API endpoint's URL. You can then provide a new brand_name and/or update the fields within the data payload.
Important!
The data payload you send will completely replace the existing data for the brand. Therefore, you must include all required fields, not just the ones you wish to change.
Request
curl --location --request PUT 'https://brands-api.numbers-registration.staging.sinch.com/v1/projects/27eb83b8-6030-491b-a3f5-2fc4b92a3aee/brands/01k7h5y64mh4fwcmxxa48h9m75' \
--header 'Content-Type: text/plain' \
--header 'Authorization: .....' \
--data-raw '{
"brandName": "My New Brand2",
"data": [
{
"legal_entity_type": "Corporation",
"name": "Abc Store Corp.",
"symbol": "SNC",
"url": "https://abc-sinch.net"
},
{
"city": "Miami",
"country": "US",
"state": "Florida",
"state_code": "FL",
"street": "1450 SW 22nd St",
"zip": "33145"
},
{
"federal_tax_id": "234342344"
},
{
"email": "contact@abcsinch.com",
"first_name": "abc",
"last_name": "Sinch",
"phone": "+13054454855"
}
],
"callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49"
}'Response
{
"brandId": "01k7h5y64mh4fwcmxxa48h9m75",
"brandName": "My New Brand2",
"brandMetadataId": "e442df25-e1fb-4651-b841-aca1073cf976",
"status": "NEW",
"data": [
{
"legal_entity_type": "Corporation",
"name": "Abc Store Corp.",
"symbol": "SNC",
"url": "https://abc-sinch.net"
},
{
"city": "Miami",
"country": "US",
"state": "Florida",
"state_code": "FL",
"street": "1450 SW 22nd St",
"zip": "33145"
},
{
"federal_tax_id": "234342344"
},
{
"email": "contact@abcsicnh.com",
"first_name": "Abc",
"last_name": "Sinch",
"phone": "+13054454855"
}
],
"logs": [
{
"status": "NEW",
"comment": "",
"author": "AGENT",
"createTime": "2025-10-14T10:58:27.111076"
},
{
"status": "NEW",
"comment": "",
"author": "AGENT",
"createTime": "2025-10-14T11:02:31.122552"
}
],
"callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49",
"createTime": "2025-10-14T10:58:27.095235",
"updateTime": "2025-10-14T11:04:06.2884"
}If the callback URL was specified in the CreateAndSubmit Request endpoint, then callback events will be received once the brand state changes.
When a brand is first submitted, it receives a NEW status. Once it is picked up for the review process, its status will be updated to PENDING_REVIEW.
This PENDING_REVIEW status confirms that the brand is now actively in the queue for internal review by our team. Once the review is complete and the status changes again (for example, to APPROVED or REJECTED), a callback notification will be sent to the callback_url you provided.
Please, read carefully the callback configuration API documentation to see how to authenticate this event.
{
"eventId": "01k6n0nva5enpgwehc8xqj80wg",
"eventType": "BRAND_STATUS_UPDATE",
"projectId": "27eb83b8-6030-491b-a3f5-2fc4b92a3aee",
"resourceId": "01k6n04h28hn8m29a77ee3bj4p",
"resourceType": "US_SHORT_CODE_REGISTRY",
"status": "PENDING",
"createTime": "2025-10-03T12:27:46.859110Z"
}