Close mobile menu

API Reference

OverviewSMSVoice CallingVoice MessagingConversationsOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRReportingBalanceLookupContactsGroups

Partner Accounts

MessageBird’s Partner Accounts API allows you to programmatically set up a Partner Network within your own software or cloud service. You can manage and control the delivery of MessageBird’s products, as well as the consumption and spend between different customer accounts.

The Partner Accounts API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.


API Endpoint

All URLs referenced in MessageBird's Partner Accounts API reference have the base URL in the code snippet on the right side.

API Endpoint

https://partner-accounts.messagebird.com/

Partner Accounts

A partner is a company that resells MessageBird’s products to its own customers. MessageBird’s Partner Accounts are those which have the capability to create Child Accounts.


Child Accounts

MessageBird’s Child Accounts are regular accounts that are "owned" by your Partner Account. By using a Child Account, you can segment each of your customers to use MessageBird’s products and keep it separate from all the rest. This will allow you to easily manage the activity and resources of each customer independently.


Authorization

To use MessageBirds APIs, you need to first sign up for free at www.messagebird.com.

You'll need to set an access key to authenticate yourself. You can create, manage, and retrieve your API keys (both test and live) from the MessageBird Dashboard.

To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.

You have to have a privilege to be able to access the MessageBird’s Partner Accounts

Authorization error (403):

{
"message": "Not privileged to request the resource."
}

Formats and Headers

All API responses are in JSON.

POST and PUT requests to the API must contain a JSON-formatted payload in the request body.


Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, a missing or wrong parameter).

In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.

MessageBird uses standard HTTP status codes to indicate success or failure of an API request:

  • Codes in the 2xx range indicate that a request was processed successfully
  • The 4xx range indicates that there was an error - for example, due to authentication, a missing or wrong parameter. Don't worry, the body of the response includes a JSON-formatted response that tells you exactly what is wrong. If you're stuck, feel free to contact support; we're happy to help you out.
  • A 5xx status code indicates that something went wrong on our end.

Error Object Example

{
"type": "https:\/\/tools.ietf.org\/html\/rfc2616#section-10",
"title": "An error occurred",
"detail": "Client error Customer Id not found"
}

Attributes

AttributeTypeDescription
typestringA type error definition.
titlestringA human-readable title of the error.
detailstringWhat kind of error occurred.

Create a Child Account

Create a new Child Accounts which will be related to the Partner Account that the access key belongs to.

Parameters:

AttributeTypeDescriptionrequired
namestringThe name of the subaccount. This name will be displayed in the invoices as well.Yes
Definition:
POST https://partner-accounts.messagebird.com/child-accounts/
Request:
curl -X POST "https://partner-accounts.messagebird.com/child-accounts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-d '{"name":"MessageBird Ltd."}'
Response:
{
"id": 6249799,
"name": "Partner Account 3 Sub 1",
"accessKeys": [
{
"id": "6912036c-dd42-489b-8588-8c430aec37ef",
"key": "Hb85uQhmgvXXlHK9h3SHaAC4V",
"mode": "live"
},
{
"id": "cc620896-33fb-415c-9af1-909123937321",
"key": "idG2gFSMayEiFRftcStmBxc71",
"mode": "test"
}
],
"signingKey": "7qxJg4lsDKLAEBXAdxyarcwwvDn7YB00",
"invoiceAggregation": true
}

Edit a specific Child Account

Edit a Child Account related to the Partner Account that the access key belongs to.

Parameters:

AttributeTypeDescriptionrequired
namestringThe name of the subaccount. This name will be displayed in the invoices as well.Yes
idintegerSubaccount Id.Yes
Definition:
PATCH https://partner-accounts.messagebird.com/child-accounts/{id}
Request:
curl -X "PATCH" "https://partner-accounts.messagebird.com/child-accounts/6249799" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-H 'Content-Type: application/json'
-d '{"name":"MessageBird Ltd."}'
Response:
{
"id": 6249609,
"name": "Partner Account 1 Sub 2"
}

Fetch a specific Child Account

This endpoint will retrieve the complete data from the Child Account that has been provided.

Parameters:

AttributeTypeDescriptionrequired
idintegerSubaccount Id.Yes
Definition:
GET https://partner-accounts.messagebird.com/child-accounts/{id}
Request:
curl -X GET "https://partner-accounts.messagebird.com/child-accounts/6249609" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Response:
{
"id": 6249609,
"name": "Partner Account 1 Sub 1",
"invoiceAggregation": true
}

Fetch all the Child Accounts

This endpoint will retrieve limited data for all Child Accounts. The default and maximum number of Child Accounts' items per page is 100. You can decrease that number by using the limit parameter. If you want to fetch the details for a single Child Account, you can use Fetch Subaccount Details

Parameters:

AttributeTypeDescriptionrequired
pageintegerPageNo
limitintegerLimit, number of items per page (Default/Max. 100)No
Definition:
GET https://partner-accounts.messagebird.com/child-accounts/
Request:
curl -X GET "https://partner-accounts.messagebird.com/child-accounts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Response:
[
{
"id": 6249623,
"name": "Partner Account 1 Sub 1"
},
{
"id": 6249654,
"name": "Partner Account 1 Sub 2"
},
{
"id": 62496654,
"name": "Partner Account 1 Sub 3"
}
]

Delete Child Account

Delete the Child account, the token will be no longer valid. Once the Child Account has been deleted, it won’t be able to use the services anymore.

Parameters:

AttributeTypeDescriptionrequired
idintegerSubaccount Id.Yes
Definition:
DELETE https://partner-accounts.messagebird.com/child-accounts/{id}
Request:
curl -X "DELETE" "https://partner-accounts.messagebird.com/child-accounts/6249799" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-H 'Content-Type: application/json'
Response:
{}

Reporting

You can use the Reporting APIs to fetch consumption data for respective subaccount.

Next upVerify

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings