Application Integration
1. Overview
To support customers' personalized business requirements better, DM Hub REST API can interact with DM Hub by programming. You can use Open API to access and export data such as customers, customer behavior, customer tags, customer groups, orders, etc. First, you need to create an application in DM Hub, then get the corresponding App ID and App Secret of the application to call the API.
2. Differences between new version and old version
The system has launched a new version of application integration recently, which needs to call API v2 when using the new version( v2 now is still the Beta version, while the old version uses API v1 ). So you should pay attention to the versions when creating the applications.
- Application permission : The new and old versions have different classifications of permissions.
- IP whitelist : IP whitelist of the old version is global settings and takes effect for all applications. The new version can set the corresponding IP whitelist for each application separately.
- API : Old version needs to be used with API v1, the new version needs to be used with API v2. Note: In the application list of the old version, you can migrate an application to the new version. The migration does not change App ID and App Secret, you need to call API 2.0 to implement related features after migration. You can set relevant API permissions in the pop-up window, and you can continue to set the IP whitelist of the application in the new version after finishing the migration.
3. Operation Entry
"Application Integration" entry : [Settings]-[System Integration]-[Application Integration]
The application displays the old version by default
4. Applications of the old version
4.1 Create new applications
As shown in the image below, when you create an application, you could fill in the following information in turn. Please check the permission restrictions of the corresponding API whether the application permissions require read or write permissions.
After clicking OK, you can view the App ID and App Secret of the application. To ensure the security of the account, please safekeeping the App Secret. App Secret will no longer be displayed after closing the window. If you need to get it, you need to generate a new App Secret.
The App Secret can be reset on the application list page.
4.2 Add IP whitelist
Set the current status to the startup, the add the whitelist.
4.3 Migrate to the new version
The migration does not change App ID and App Secret. After migration, you need to call API 2.0 to implement related functions. You can set relevant API permissions as the image shows below. You can set the application IP whitelist in the new version interface.
5.New Version
5.1 Version and URI
DM Hub REST API version 2 is the latest version, and its address structure has the following form :
<table><tr><td bgcolor=rgb(41,45,62)> <font color=white> https://api.convertlab.com/v2/{RESOURCE_PATH}</font></td></tr></table>
RESOURCE_PATH is the API path of a specific resource.
5.2 Create Applications
Switch to the new version of the application interface, create applications, then set IP whitelist.
After creating the application, please safekeeping the App ID and App secret.
5.3 Obtain access_token
DM Hub REST API uses OAuth v2.0 protocol as the authorization protocol. When accessing DM Hub REST API, you need to bring an access token as an authentication credential. Developers need to save it properly. Access_token is valid for 2 hours and needs to be refreshed regularly.
Request Get https://api.convertlab.com/v2/oauth2/token?app_id={APPID}&secret={SECRET}&grant_type=client_credentials Request Sample Request Address
Get https://api.convertlab.com/v2/oauth2/token?app_id={APPID}&secret={SECRET}&grant_type=client_credentials
| Parameters | Required | Description |
|---|---|---|
| app_id | Yes | App ID of the application |
| secret | Yes | App secret of the application |
| grant_type | Yes | Authorization type,must be client_credentials |
Return Sample
{
"access_token": "dae7*********************e486",
"expires_in": 7200
}
| Parameters | Type | Description |
|---|---|---|
| access_token | String | API credential |
| expires_in String | Valid time of API credential |