Skip to main content

​
Overview

Jobs can be either read or write. Read jobs will fetch data from your source while write jobs can perform actions such as filling out a form or making a payment. Jobs run asynchronously and Deck notifies you of progress and status via webhooks. Your new Link will appear in the left navigation of the Deck Dashboard. You’ll see a list of jobs created under your link:
  1. EnsureConnection: This is a job created by Deck and used to open connections to your source. It will always be your first job you call, whether you call it directly or via the Deck Widget.
  2. Your source-specific jobs: Deck generates one to several jobs that match your use case and work to fetch your target data or write to a source.
  3. CloseConnection: Another Deck-provided job to close your open connections.

​
Run a Job

Once you’ve received an access_token, you can use that token to run a job. To run a job, include the access_token and job_code in your request as well as any custom inputs scoped to your job. Deck will run the job against the active connection and a webhook will return the output of the job. 
curl --request POST \
  --url https://sandbox.deck.co/api/v1/jobs/submit \
  --header 'Content-Type: application/json' \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>' \
  --data '{
  "job_code": "FetchDocuments",
  "input": {
    "access_token": "access-sandbox-34343434-bcbc-34bc-34bc-343434343434",
    "key1": "value1",
    "someNumber": 123.45,
    "someBoolean": true,
    "someArray": [
      "a",
      "b"
    ],
    "nestedObject": {
      "k": "v"
    }
  }
}'
The job will return a webhook with the job’s output. 
{
  "webhook_type": "Job",
  "webhook_code": "FetchDocuments",
  "job_guid": "67901dec-aea2-451d-abee-b44be31ae043",
  "output": {
    "document_count": 123,
    "document_list_url": "/api/v1/jobs/documents/list"
  },
  "environment": "Sandbox"
}

​
Handle Job Success

When a job succeeds, Deck sends a webhook with the job ID and any output (such as documents). At that point you can process the results in your system: store them, trigger downstream jobs, or present them to the user. 
{
  "webhook_type": "Job",
  "webhook_code": "FetchDocuments",
  "job_guid": "67901dec-aea2-451d-abee-b44be31ae043",
  "output": {
    "document_count": 123,
    "document_list_url": "/api/v1/jobs/documents/list"
  },
  "environment": "Sandbox"
}
Once you’ve consumed the data, you should also consider closing the connection if it’s no longer needed. Calling CloseConnection, an auto-provisioned job similar to EnsureConnection, ends the active session and revokes access. If you expect to run more jobs soon for the same user, you can leave the connection open. If you don’t close a connection, it will close automatically 1 hour after it was opened. Run the CloseConnection job: 
curl --request POST \
  --url https://sandbox.deck.co/api/v1/jobs/submit \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "job_code": "CloseConnection",
  "input": {
    "access_token": "<access-token>",
  }
}'

​
Handle Job Failure

When a job fails, Deck notifies you by webhook with an error payload that includes the job ID, error code, and message. Deck never retries jobs automatically. 
{
  "webhook_type": "Job",
  "webhook_code": "FetchDocuments",
  "job_guid": "67901dec-aea2-451d-abee-b44be31ae043",
  "error": {
    "error_category": "JOB_ERROR",
    "error_code": "SOURCE_TIMEOUT",
    "error_message": "The source did not respond in time", 
    "display_message": "We couldn't complete your request because the source took too long to respond. Please try again."
  },
  "environment": "Sandbox"
}