API Reference

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

In order to use the APIs of the MessageBird Connectivity Platform, you need to have an account and log in to the Dashboard of the Connectivity Platform.

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

Attribute	Type	Description
type	string	A type error definition.
title	string	A human-readable title of the error.
detail	string	What 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:

Attribute	Type	Description	required
name	string	The 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:

Attribute	Type	Description	required
name	string	The name of the subaccount. This name will be displayed in the invoices as well.	Yes
id	integer	Subaccount 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:

Attribute	Type	Description	required
id	integer	Subaccount 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:

Attribute	Type	Description	required
page	integer	Page	No
limit	integer	Limit, 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:

Attribute	Type	Description	required
id	integer	Subaccount 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.

Is this page useful?

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