Overview

You can use the Data Jobs API to run and trigger Data Job Transformations.

• Learn about Data Jobs and Transformations here

API set name: datajobs

Authentication

Cordial's core APIs use HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Methods, parameters, and examples

• POST/v2/datajobs/{key}/transform
• POST/v2/datajobs/{key}/trigger

POST/v2/datajobs/{key}/transform

• * Required

  Parameter	Type	Description	Examples
  * key	string	The unique Data Job/Transformation key value. Created in the UI.	"DemoDataTransformation" "45:6751e16b9ec5c7bc9f0296ba:rm123456789"
  * body	object	Data object that will be transformed. Must be in JSON format.	This could be any piece of customer or product data: contact attributes, products, orders, events, etc. See example JSON request.

• The following is an example contact object (in JSON) that will be transformed using the transformation script you set up in the UI.

  {
    "id": "contact_12345",
    "firstName": "Kilgore",
    "lastName": "Trout",
    "email": "kilgore.trout@example.com",
    "phone": {
      "mobile": "+1-555-123-4567",
      "work": "+1-555-987-6543",
      "home": null
    },
    "address": {
      "street": "123 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "90210",
      "country": "United States"
    },
    "personalInfo": {
      "dateOfBirth": "1985-03-15",
      "preferredContactMethod": "email"
    }
  }
  

• The following will:

  • Use the email address as the lookup key to find the contact.
  • Update or create the contact record with the first name and last name.
  • Suppress any triggered messages that might normally fire based on contact updates.

  {$contact_upsert.data.channels.email.address = 'kilgore.trout@example.com'}
  {$contact_upsert.lookup_key = "email:{$contact_upsert.data.channels.email.address}"}
  {$contact_upsert.data.firstName = 'Kilgore'}
  {$contact_upsert.data.lastName = 'Trout'}
  {$contact_upsert.suppressTriggers = true}
  {$utils-upsertContact($contact_upsert.data, $contact_upsert.lookup_key, $contact_upsert.suppressTriggers)}  

• The following URL in conjunction with the JSON will trigger the Transformation.

  https://api.cordial.io/v2/datajobs/DemoDataTransformation/trigger
  

• The following is an example response when the POST request is successful. You can view the status of your Data Transformation on the Jobs page.

  { 
    "success": true, 
    "message": "Transformation is processing."
  }
  

POST/v2/datajobs/{key}/trigger

• * Required

  Parameter	Type	Description	Examples
  * key	string	The unique Data Job/Transformation key value. Created in the UI.	"DemoDataJob" "45:6751e16b9ec5c7bc9f0296ba:rm123456789"

• The following URL will trigger an existing Data Job.

  https://api.cordial.io/v2/datajobs/trigger
  

• The following is an example response when the POST request is successful.

  {
    "success": true,
    "message": "Transformation is triggered.",
    "dabID": "45:6751e16b9ec5c7bc9f0296ba:rm202412061755",
    "jobIds": [
      "67533a74b49e21e6bd061788"
    ]
  }
  

Test in Swagger

You can access and test Cordial's APIs in Swagger.

Error responses

Below is a list of errors specific to the Data Jobs API endpoint along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API error responses page.