Use these REST APIs to perform various REST functions. For information about APIs that you can use for integration with the Mobile App Messaging Solution, see APIs for integration. To ensure that you are able to access the most accurate information, be sure to use the link that corresponds to your pod.
For all of the API calls below, the client token, secret and refresh token are bound to the issuing Organization only.
- Pod 1 – https://api1.ibmmarketingcloud.com/restdoc
- Pod 2 – https://api2.ibmmarketingcloud.com/restdoc
- Pod 3 – https://api3.ibmmarketingcloud.com/restdoc
- Pod 4 – https://api4.ibmmarketingcloud.com/restdoc
- Pod 5 – https://api5.ibmmarketingcloud.com/restdoc
- Pod 6 – https://api6.ibmmarketingcloud.com/restdoc
- Pod 7 – https://api7.ibmmarketingcloud.com/restdoc
- Pod 8 – https://api8.ibmmarketingcloud.com/restdoc
Note: Response codes can be found here.
Channels (Operations that are related Push and SMS)
To use these API calls, you must first obtain OAuth credentials.
| Push Sends
(POST) |
Use this REST API to perform a push notification send to contacts.
Note: Inbox and Inapp for Windows is supported.
|
| Push Published Messages
(POST) |
Use this REST API to send a push notification to a contact source. |
| Send a Push notification
(POST) |
Use this REST API to send a push notification with inline content to a contact source.
Note: Inbox and Inapp for Windows is supported.
|
| Push Rich Content
(POST) |
Use this REST API to create rich content.
Note: Inbox and Inapp for Windows is supported.
|
| Get Rich Push Content
(GET) |
Use this REST API to get rich content. |
| InAppContent
(POST) |
Use this REST API to create inapp messages. Then use another api, such as the Push to Contact API, to send your InApp message that was already created.. |
| Send SMS to a Contact Source
(POST) |
Use this REST API to send a published SMS message to a contact source. |
| Send SMS to input contacts
(POST) |
Use this REST API to send a Transactional SMS message to input contacts.
Note: SMS phone numbers must include country code.
|
| Perform a SMS send to external consent contacts
(POST) |
Use this API to send SMS messages to contacts not required to be in your SMS database. Mobile numbers that are not found in your SMS database are added to your SMS database for event processing. Consent management for this API is external to and is the responsibility of the API user.
Note: SMS phone numbers must include country code.
|
| SMS Send Status
(GET) |
Use this REST API to get an SMS send status for both Transactional SMS API and SMS External Consent API. |
| Retrieve published messages
(GET) |
Use this REST API to Retrieve published messages for SMS or push. Provide type in path as SMS or push for respective messages. |
| Get all SMS Programs for an Org
(GET) |
Use this API to retrieve a list of all active SMS Text to Join programs for an Org. |
| Get an SMS Program status
(GET) |
Use this REST API to get SMS Text to Join program details for a given SMS Program ID. |
| Create an SMS Program
(POST) |
Use this REST API to create an SMS Text to Join program to be used with the SMS UBX Sender feature. .
Note: This API is only applicable when the Org is provisioned to send SMS’s via UBX Sender.
|
| Update an SMS Program attributes for a given SMS Program
(PUT) |
Use this REST API to update attributes of an existing SMS Text to Join program that was created to be used with the SMS UBX Sender feature.
Note: This API is only applicable when the Org is provisioned to send SMS’s via UBX Sender.
|
| Delete an SMS Program
(DELETE) |
Use this REST API to delete an SMS Text to Join program that was created to be used with the SMS UBX Sender feature.
Note: This API is only applicable when the Org is provisioned to send SMS’s via UBX Sender.
|
Note: Some providers limit the number of push or SMS messages to the same device within a period of time. Repeatedly calling these APIs over a short period of time can result in fewer delivered messages than calls.
Contact Sources
| Retrieve BCC
(GET) |
Use this REST API to get the Contact Source’s BCC Address. |
| Update BCC
(PATCH) |
Use this REST API to set the Contact Source BCC Address. |
Databases
| LookUp Keys
(DELETE) |
Use this REST API to delete the lookup key for a database field. The lookup key is deleted, if allowed. |
| LookUp Keys
(GET) |
This REST API can be used to get the lookup key for a database field.
Note: The lookup key cannot be used until it reaches an ACTIVE status.
|
| LookUp Keys – All
(GET) |
Use this REST API to get ALL the lookup keys for this database.
Note: A lookup key cannot be used until it reaches an ACTIVE status.
|
| LookUp Keys
(PUT) |
Use this REST API to create a lookup key for a database field. The lookup key’s information is returned, if it is successfully created or exists.
Note: The lookup key cannot be used until it reaches an ACTIVE status.
|
| Channel Consent
(GET) |
Use this REST API to get the SMS consent value for a given database, channel, qualifier, and destination. |
| Channel Consent
(PUT) |
Use this REST API to update or insert the consent value for a given database, channel, qualifier, and destination. |
| Contact by Channel
(GET) |
Use this REST API to get the contact for a given database, channel, qualifier and destination. |
| Contact by Channel
(PATCH) |
Use this REST API to add or update a contact with the given contact data using channel information. |
| Contact by LookUp Key
(PATCH) |
This REST API updates the Contact with the given contact data using lookup key pair. |
| Contact by LookUp Key
(GET) |
This REST API retrieves data for Contact(s) with the given lookup key filter(s) from the Database. |
| Contact API
(PATCH) |
This REST API updates the Contact with the given contactId in the Database with the given databaseId. |
| Contact API
(POST) |
This REST API creates a Contact in a given Database. |
| Contact API
(GET) |
Use this API to retrieve a contact representation for a given databaseId and contactId. |
| Contact Messages
(GET) |
This REST API retrieves the messages for the given Contact in the given Database.
Note: Data is retrieved for the last 31 days. Users are unable to modify the date range.
|
| CRM Campaigns Manager
(PUT) |
This REST API creates or updates a record in a Crm campaign for a given contact, databaseId and crmCampaignKey. |
| Establish Identity
(PUT) |
Use this REST API to update or merge contact with existing contact matching consent. |
| Event Type Mappings
(GET) |
This REST API returns the Event Type Mappings to a given Database. |
Relational Tables (Operations Related to Relational Tables)
| Associated Relational Table Data API (POST) | Use this API to load the data from your relational table. Accepted date format: MM/dd/yyyy |
Events (Operations Related to Universal Behaviors)
These operations will allow you to bypass UBX and use only Watson Campaign Automation
| events
(GET) |
Retrieve event submission errors. Use this REST API to periodically check to see if any of your event submissions have failed validation. |
| events
(POST) |
Use this REST API to submit new behavioral events. Here are the event codes and event names to use for the events/submission service. To understand the attributes associated with these events, use the eventtypes/{code} service inputting the event code shown. |
Organization Settings
| Retrieve BCC
(GET) |
Use this REST API to get the Org BCC Address. |
| Update BCC
(PATCH) |
Use this REST API to set the Org BCC Address. |
Programs
| Retrieve a Program
(GET) |
Use this REST API to retrieve a program with the given id. |
| Retrieve a List of Programs
(GET) |
Use this REST API to retrieve a program with the given id. |
| Create a Program
(POST) |
This REST API creates a program with the provided parameters. |
| Update a Program
(PUT) |
Use this REST API to update a program. |
Web
| Web Tracking
(GET) |
This REST API provides the script to be embedded in a site that wants to implement web tracking. |
Messages (Operations that are related to Messages)
| Retrieve offer details for a scheduled messages Id
(GET) |
Use this API to Retrieve offer details for a scheduled message ID. |
Learn more:
- Bulk Export (BEX) REST API
- Create Rich Content API
- Exporting SMS messages from the SMS Campaign Manager using a REST API
- Get a list of all active Text to Join SMS programs for an Org
- GET Contact by Lookup Key REST API
- Get Rich Content API
- How are APIs for simple mobile app push messages different from rich mobile app push message APIs?
- In-App Content API
- Push to Contact API
- Push to Segment API
- Push to Segment API with inline content
- REST API for adding a column to an existing Relational Table
- REST API Response Codes
- REST API SMS External Consent
- REST API to get an SMS Program status
- REST API to get published messages from Watson Campaign Automation
- REST API to Send Push to Contact Source
- REST API to send SMS to Contact Source
- REST API to Send Transactional SMS Messages
- Update an SMS Program Attribute
- Use Case: BCC REST API
- Use Case: REST API to map Universal Behaviors
- Use Cases for REST APIs
Is there a way to add rows to a Relational Table via the REST API?
Hello Eric,
While a REST API won’t help you, the XML API, Import to a Relational Table should help. You’ll find more information here, approximately a quarter of the way down the page.
https://developer.ibm.com/customer-engagement/docs/watson-marketing/ibm-engage-2/watson-campaign-automation-platform/xml-api/db_mgmt_user_xml_intfc/#Importtoarelationaltable
Thank you,
Jeri
Hi Rest API does not support Sending an Email or scheduling mailing as in XML api???
Regards,
Naveen
Correct. In order to send or schedule an email you need to use the XML API.
I Get an error saying database not found though i can locate it using the portal. its on engage7
Hello,
In order to assist you better, can you provide the name of your Organization, the name of the database and which REST API call you are using?
Thank you
Jeri
Hi does rest provide Import and Export of Database , contact list etc as In SOAP and XMLAPI?
Hello,
Rest API doesn’t provide for the operations you mention. Those can only be performed using SOAP or XML API.
Thank you
HI ,
I need to update the records in silver pop db from the Java API..will it possible to do that.
If yes,Kindly provide me the steps to do that.
Thanks
Its late to reply but, Yes its possible You can refer the XML API guide and can update the Database , if you still need help just reply Thanks
hey,
need help in adding recipients to database through java.
Please assist
Hi,
how do I get all contacts where columnX = ABC?
regards,
bruno
Hi, Where is the documentation for the return objects?
For example, we see things like attributes in the meta object, but what are the content of the attributes object?
What are the exact types of all fields of all response objects, so we can correctly parse them?
I need to automate the process for deleting or opt out a contact from IBM watson marketing using their Database API calls. How can I delete a contact using API that have been added by API calls.
Basically we have have a master suppression list database from where we need to remove contacts who have previously unsubscribed but now have subscribed again.
I have looked into to silverpop swagger api https://api3.ibmmarketingcloud.com/restdoc/ but couldn’t find what I am looking for.
Can anyone give me an insight on this?
Hello Senam,
Have you tried the Remove a contact call? https://developer.ibm.com/customer-engagement/tutorials/remove-a-contact/ ? CAUTION: Removing a recipient from a database also removes all tracking for mailings sent to the recipient and cannot be undone.
Thank you
Jeri
Is it possible to delete a contact via the REST API? I’m writing some integration tests and would like to create (POST), fetch (GET), modify (PATCH) contact info, but the API doesn’t support the DELETE verb, it seems.
Hello Tarjei,
No RESTful API currently exists for removing a contact from a database, only the RemoveRecipient XML API for now. It remains an item on the API roadmap.
Thank you,
Jeri
Hi,
I am trying to add a contact through contact POST API, the payload I am sending is { email: “myEmail Address” }, but, I am getting an error in generalError – “Could not validate recipient; required unique key column values were not provided”.