Partner API

The Partner API allows you to interact with our platform programatically.

This allows Partners to build a frictionless user journey for clients and automate processes.

In order to get started with the Partner API you need two things: your Partner ID and your Partner Hub long credentials.

Partner ID

The Partner ID is an unique ID that will be used for most API actions.

The easiest way to find your Partner ID is to log into the 360dialog Partner Hub on your browser and go to the "Partner Integration" section.

To understand more about the Partner ID and credentials, see the Architecture and Security documentation.

Login Credentials

All requests to the Partner API are secured by a Bearer Token, which can be obtained by providing a username (email) and a password. For this, you can either use a personal user account or set up a system user specifically for the API tasks. Make sure you have this information at hand when starting to work with the Partner API.

For more information on Authorization have a look at the API description and the token endpoint description.

Base URL

The 360dialog Partner API allows to automate different processes of account management, usage statistics collection and let you know about status changing of your client’s accounts.

The default base URL for the 360dialog Partner API is https://hub.360dialog.io/api/v2

The basic principles of interaction with Partner API are the same as for Messaging API.

API Authentication Methods

Authentication

The Partner API supports two authentication methods: Bearer Token and API Key. While API Key authentication is the recommended approach, Bearer Tokens will remain valid for a transition period.

1. API Key Authentication (Recommended)

API Key authentication allows secure access to the Partner API without requiring user credentials. Each request must include a valid API key in the request headers.

How to Obtain an API Key

• Navigate to the API Keys section in the Partner Dashboard

• Generate an API key. Store the key securely, as it grants access to the Partner API. It will only be displayed once

Using the API key

Include the API Key in the request header:

x-api-key: YOUR_API_KEY

Example Request

curl -X GET "https://hub.360Dialog.io/api/v2/partners/<partner-id>" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Best Practices for API Authentication

• API Keys Usage: Use API Keys for service-to-service communication.

• API Keys Rotation: Rotate keys periodically to maintain security.

• Secure Storage: Always store API keys and credentials securely. Avoid exposing them publicly or hardcoding them in client-side code - use environment variables instead

• Error Handling: Handle authentication errors gracefully. Common errors include:

  • 401 Unauthorized: Invalid or missing authentication credentials.

  • 403 Forbidden: Valid credentials, but insufficient permissions.

2. Bearer Token Authentication (Deprecated)

During the transition period, Bearer Token authentication will still be supported. To obtain a Bearer Token, provide your username (email) and password.

Request OAuth token for any Partner API request

POST https://hub.360dialog.io/api/v2/token

Request example

curl --request POST --url https://hub.360dialog.io/api/v2/token --header 'Authorization: ' --header 'Content-Type: application/json' --data '{ "username": "[email protected]", "password": "123StrongPass4Me!" }'

Request Body

Name	Type	Description
username*	string	Example: [email protected]
password*	string	Example: 123StrongPass4Me!

200: OK

{
  "access_token": "string",   >> Token you should use for Authorization
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 86400
}

401: Unauthorized Means your login credentials are wrong

After token is received, use this access token in your authorization header:

"Authorization": "Bearer <your-access-token>"

Bearer Tokens and Partner API Key (via X-API-KEY header) are authentication methods specifically designed to use with the Partner API. It cannot be used in combination with the Messaging API.

For the Messaging API, the supported authentication method is through the use of D360-API Keys - Adding D360-API-KEY in the header with your Client's unique API Key as a value will grant access to Messaging API. See how to retrieve an API key here.

Partner Hub Webhook URL

A Webhook URL is required for you to receive webhook events about account signup and statuses..

Set Partner Hub Webhook URL

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/webhook_url

Request example

curl --request POST --url https://hub.360dialog.io/api/v2/partners/partner_id/webhook_url --header 'Authorization: ' --header 'Content-Type: application/json' --data '{ "webhook_url": "https://example.com/webhook" }'

Path Parameters

Name	Type	Description
partner_id*	string	Your Partner Hub ID

Request Body

Name	Type	Description
webhook_url*	string	The Webhook URL you want to set

200: OK

{
  "webhook_url": "string",
  "brand_name": null,
  "id": "string",
  "logo_url": null,
  "onboarding_deeplink_add_params": true,
  "payment_plan": {},
  "payment_required": true
}

After the Webhook URL is set, you will start receiving events about the accounts registered under your Partner Hub. See all events available today in the Partner API here.

You can check the Webhook URL configured with the endpoint below.

Get Partner Hub Webhook URL

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/webhook_url

Request example

curl --request GET --url https://hub.360dialog.io/api/v2/partners/partner_id/webhook_url --header 'Authorization: ' --header 'Content-Type: application/json'

Path Parameters

Name	Type	Description
partner_id*	string	Your Partner Hub ID

200: OK

{
  "webhook_url": "string"
}

Partner Hub Redirect URL

The Redirect URL indicates where a client should be redirected to after they have completed the Integrated Onboarding flow. Having a Redirect URL set is required to use Integrated Onboarding.

You can also add a Redirect URL in your Partner Hub.

Set Redirect URL for your Partner Hub

PATCH https://hub.360dialog.io/api/v2/partners/{partner_id}

Request example

curl --request PATCH --url https://hub.360dialog.io/api/v2/partners/partner_id --header 'Authorization: ' --header 'Content-Type: application/json' --data '{ "webhook_url": "string", "partner_redirect_url": "string" }'

Path Parameters

Name	Type	Description
partner_id*	string	Your Partner Hub ID

Request Body

Name	Type	Description
webhook_url*	string	Your Webhook URL which needs to be previously created - see how in the Partner API integration document
partner_redirect_url*	string	The Redirect URL you will use

200: OK

{
  "webhook_url": "string",
  "partner_redirect_url": "string",
  "brand_name": null,
  "id": "string",
  "logo_url": null,
  "onboarding_deeplink_add_params": true,
  "payment_plan": {},
  "payment_required": true
}

Partner Hub Information

Use the GET request to check information regarding your 360dialog Partner Hub.

Get Partner Hub information

GET https://hub.360dialog.io/api/v2/partners/{partner_id}

Request example

curl --request GET --url https://hub.360dialog.io/api/v2/partners/partner_id --header 'Authorization: ' --header 'Content-Type: application/json'

Path Parameters

Name	Type	Description
partner_id*	string

200: OK

{
    "allow_client_to_add_phone_no": true, 
    "billing_system": "string", //Indicates the type of partner payment
    "blocked_new_submission": false,
    "brand_name": "string", //Name currently set for this Partner Hub
    "country": "US",
    "id": "string", //Partner ID
    "logo_url": "string", //Logo currently set for this Partner Hub
    "onboarding_deeplink_add_params": false,
    "partner_redirect_url": "https://360dialog.com", //Redirect URL currently set for this Partner Hub
    "payment_plan": {},
    "payment_required": false,
    "settings": { //Tech Provider Information
        "account_sharing": {
            "business_manager_id": "string", 
            "solution_id": "string"
        },
        "default_data_localization_region": "DE", //Default data storage for this Partner Hub
        "partner_change_request": {
            "auto_approve": false 
        },
        "standard_tiered_pricing_enabled": true
    },
    "webhook_url": "string" //Webhook URL currently set for this Partner Hub
}