API (Application Programming Interface)
Marketing Connector provides a set of APIs that users can call from external applications to initiate the various Marketing connector operations e.g. startsync/stopsync for a specific connector etc. Currently APIs are available for the following operations:
- Getting Authentication token for calling the APIs
- API to start sync for a connector
- API to stop sync for a connector that has been syncing
- Get current sync status of a conenctor
How the APIs are accessed?
When start Marketing connector from your Heroku dashboard, marketing connector can use Heroku SSO to authenticate you and allow access to your dashboard.
However, the APIs are called from your external application, so, Heroku SSO is not available from external application. Therefore, marketing connector uses a token based authentication process to allow you access to the APIs for your instance of marketing connector. In general the process works like the following:
- You are provided an API Key for your instance of marketing connector which you can pick up from your dashboard ‘additional configuration’ menu. You also have the option to regenerate the API Key should you have reasons to believe that the API Key has been compromised.
- When you access the APIs, you will need to use the API Key and get an access_token. The access_token has an expiration time and the API returns expiration time of the access_token.
- You can save the access_token in your local storage and continue to use it till it expires
- When you use an access_token which has expired, the API call will return an error which will indicate that the access_token has expired. In that case, you will need to get a new access_token before you make any new API calls.
NOTE: Make sure you keep your API Key secret and never check-in your API Key with source code to any public Github repository or public document which can be viewed by others.
API Key
It is a 32 character string in the format 8b401c38-de71-4a9f-a534-e9f0e0280234
Access_token
“access_token: {
“token”:””, //32 character string e.g. 90405c38-de71-4a9f-a534-e9f0e0210000
“expiry”:””, // Integer – number of seconds from current time the key will expire
“type”:””, // bearer is the only type we support now
};
grant_type
It is the level of API your application can call.
0 – token that will allow you to call these APIs startsync, stopsync, getsync status
Other – will be provided later
List of APIs
API to Get Authentication Token
POST /api/sync/getauthtoken
Method : POST
URL : https://mc-connect-addon.herokuapp.com/api/sync/getauthtoken
Header
No header required
Request
{
“api_key”: “,
“grant_type”: 0 // (0,1,2,3) 0 is the only type supported now
}
Response:
Success
{
“status”: 200,
“message”: “OK”,
“access_token”: {
“token”: “””,
“expiry”: 3600,
“type”: “Bearer”
}
}
Failure
{
“status”: “0/1”, // as shown below
“status_message”: “”, // as shown below
}
Status and status_message:
0- API Key do not match with our record
1- Grant type is invalid
3- Plan is not supported for API operations
API to Start Sync
POST /api/sync/startsync
Method : POST
URL : https://mc-connect-addon.herokuapp.com/api/sync/startsync
Header
Authorization: Bearer 90405c38-de71-4a9f-a534-e9f0e0210000
Request
{
“connector_name”: “PG to MC trigger2”
}
Response:
Success
{
“status”: 200,
“message”: “Sync Started”
}
Failure
{
“status”: “”, // as shown below
“status_message”: “”, // as shown below
}
Status and status_message:
0- Access Token has expired, please regenerate token
1- Requested connector not found
2- Multiple connectors exist with same name, Please rename the connector and call again
3- Plan is not Supported for API operations
4- Kafka related messages
API to Stop Sync
POST /api/sync/stopsync
Method : POST
URL : https://mc-connect-addon.herokuapp.com/api/sync/stopync
Header
Authorization: Bearer 24ff1847-0bc6-4c04-b512-46a409bbcf31
Request
{
“connector_name”: “PG to MC” // Exact name of your conenctor
}
Response:
Success
{
“status”: 200,
“message”: “Sync has stopped”
}
Failure
{
“status”: “0/1/2/3/4”,
“status_message”: “”,
}
Status and status_message:
0- Access Token has expired, please regenerate token again before calling this API
1- Requested connector not found
2- Multiple connectors exist with same name, you may rename this connector and make this API call again
3- Plan is not Supported for API operations
4- Kafka related messages
API to Get sync status
POST /api/sync/getsyncstatus
Method : POST
URL : https://mc-connect-addon.herokuapp.com/api/sync/getsyncstatus
Header
Authorization: Bearer 24ff1847-0bc6-4c04-b512-46a409bbcf31
Request
{
“connector_name”: “PG to MC trigger2”
}
Response:
Success
{
“status”: 200,
“message”: “Progress”
}
Failure
{
“status”: “0/1/2/3/4”,
“status_message”: “”,
}
Status and status_message:
0- Access Token has expired, please regenerate token again before calling this API
1- Requested connector not found
2- Multiple connectors exist with same name, you may rename this connector and make this API call again
3- Plan is not Supported for API operations
