Data Jobs API – Cordial Knowledge Base

How can we help?

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

Method	URL Path
POST	`/v2/datajobs/{key}/transform`
Triggers an advanced transformation script as set up in the UI ( Data Jobs > Create New Data Job > Transformations > Custom > Job Occurrence > API Triggered). The Data Transformation is defined by its unique `key` value and must be already created and published. Your Data Job must be set to API Triggered under the Job Occurrence setting when you create it.

* 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

Method	URL Path
POST	`/v2/datajobs/{key}/trigger`
Triggers an existing Data Job and Transformation created in the UI ( Data Jobs > Create New Data Job). In the UI, your Data Job and Transformation must be Published with a schedule set but not Enabled. Trying to use an API trigger for a Data Job that's set to Enabled result in an error.

* 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"
  ]
}

GET/v2/datajobs/{dabID}/stats

Method	URL Path
GET	/v2/datajobs/{dabId}/stats
Returns stats for a specific one-time data job

GET/v2/datajobs/{key}/runs/{runMarker}/stats

Method	URL Path
GET	/v2/datajobs/{key}/runs/{runMarker}/stats
Returns per-run statistics for recurring data job

GET/v2/datajobs/{key}/runs

Method	URL Path
GET	/v2/datajobs/{key}/runs
Returns a list of runs for recurring data job

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.

`errorKey`	Message	Modifications
`DATA_JOBS_TRIGGER_UNSUPPORTED_TEMPLATE`	Data job can't be triggered because it does not have one of the supported templates scriptedImport, scriptedExport, custom.	Make sure the Data Transformation in your Data Job functions correctly.
`DATA_JOBS_TRIGGER_RECURRING_IS_ENABLED`	Data job can't be triggered right now because recurring is enabled for it.	Disable the Recurring setting in the UI but still keep Data Job Published and Scheduled.
`DATA_JOBS_TRANSFORMATION_FEATURE_IS_DISABLED`	Current account does not support transformations through API.	Current account does not support transformations through API.
`DATA_JOBS_MISSING_TRANSFORMATION_RECORDS`	Transform record(s) should be provided.	Ensure the correct transformation records are provided.
`DATA_JOBS_AUTOMATION_KEY_NOT_FOUND`	Data Automation does not exist.	The provided key did not return a Data Automation.
`DATA_JOBS_API_TRIGGER_IS_DISABLED`	Trigger API is disabled.	Enable the API trigger.