Direct Data Intake API Code Samples

Selection of code samples that demonstrate the use of the Direct Data Intake API. Copy and edit these code samples to suit your needs.

When using the code samples, remember to replace:

  • {vanity_name} with your tenant name
  • {api_key} with your API key
  • {security_token} with a valid security token

These code samples may not include all available parameters and request body fields for each endpoint. For the endpoint's full request schema, see "Direct Data Intake" in API Reference.

Update the data intake configuration

Use this sample request to optionally change the data intake data category type. If a data category exists in your Visier tenant before using the Direct Data Intake (DDI) API for the first time, use this API to change the DDI data category type to supplemental. If the DDI API is sending the tenant's first data files, no configuration is necessary.

Copy
cURL sample request: Change the data intake configuration to supplemental
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/configs' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
--data '{
    "job": { 
        "supplementalMode": "IS_SUPPLEMENTAL"
    }
}'

The response returns an empty 200 OK success response.

To change the data category type from supplemental to primary, change supplementalMode to IS_PRIMARY.

Use the following sample request to change the data intake configuration to extension. The supplementalMode is IS_SUPPLEMENTAL and extendObjects specifies the analytic object to load using extension tables.

Copy
cURL sample request: Change the data intake configuration to extension
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/configs' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
--data '{
    "job": { 
        "supplementalMode": "IS_SUPPLEMENTAL",
        "extendObjects": "Employee"
    }
}'

Retrieve an object's data load schema

Use these sample requests to return the data load schema (or staging schema) for a given object in Visier. In this sample, the requested object is Employee_Exit.

Copy
cURL sample request: Retrieve Employee Exit's data load schema
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/schemas/Employee_Exit' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns Employee Exit's data load schema.

Copy 
{
  "schema": [
    {
      "name": "EmployeeID",
      "dataType": "TEXT",
      "isMandatory": true
    },
    {
      "name": "EventDate",
      "dataType": "DATE",
      "formats": [
        "yyyy-MM-dd",
        "MM/dd/yyyy",
        "dd-MM-yyyy"
      ],
      "isMandatory": true
    },
    {
      "name": "Record_Period_ID",
      "dataType": "DATE",
      "formats": [
        "yyyy-MM-dd",
        "MM/dd/yyyy",
        "dd-MM-yyyy"
      ],
      "emptyValuesAllowed": true
    },
    {
      "name": "Employer_Post_Termination",
      "dataType": "TEXT",
      "emptyValuesAllowed": true
    },
    {
      "name": "Termination_Reason-Termination_Detailed_Reason",
      "dataType": "TEXT",
      "emptyValuesAllowed": true
    },
    {
      "name": "Termination_Reason-Termination_Reason",
      "dataType": "TEXT",
      "emptyValuesAllowed": true
    },
    {
      "name": "Termination_Type",
      "dataType": "TEXT",
      "emptyValuesAllowed": true
    },
    {
      "name": "Sequence_Number",
      "dataType": "NUMERIC",
      "emptyValuesAllowed": true
    }
  ]
}

Start a data intake transaction

Use this sample request to start a transaction to load data into an object.

Copy
cURL sample request: Start a data intake transaction
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the new transaction's transaction ID.

Copy 
{
  "transactionId": "0403f38d-7795-4df0-b805-ba3986761a4c"
}

Upload files

Use this sample request to upload a data file for a target object into an uncommitted transaction. In this sample, the target object is Employee_Exit and the data filename is file1.csv.

Note:  

  • To upload multiple files to the same transaction, you must make multiple PUT calls.
  • You can upload the following file types:
    • Text/csv: One CSV file per call.

    • Application/zip: One ZIP folder containing a single CSV file per call.

      If you use application/zip, the filename of the CSV file must match the name of the target object. The ZIP filename can be any name. For example, if uploading data for Employee_Exit with a ZIP file, the ZIP filename is anyname.zip and the CSV filename is Employee_Exit.csv.

Copy
cURL sample request: Upload file1.csv to Employee_Exit in a transaction
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions/0403f38d-7795-4df0-b805-ba3986761a4c/Employee_Exit' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-F files=@/path/to/data/file1.csv

The response returns the upload status.

Copy 
{
  "transactionId": "0403f38d-7795-4df0-b805-ba3986761a4c",
  "status": "SUCCEEDED"
}

To send another data file to the transaction, make another request, as shown next.

Copy
cURL sample request: Upload file2.csv to Employee_Exit in a transaction
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions/0403f38d-7795-4df0-b805-ba3986761a4c/Employee_Exit' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-F files=@/path/to/data/file2.csv

Commit a transaction

Use this sample request to commit a transaction. This endpoint initiates loading all uploaded files within the transaction by starting a processing job. After committing a transaction, you cannot upload additional files to the transaction.

Copy
cURL sample request: Commit a pending transaction
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions/0403f38d-7795-4df0-b805-ba3986761a4c' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the commit status.

Copy 
{
  "transactionId": "0403f38d-7795-4df0-b805-ba3986761a4c",
  "status": "SUCCEEDED",
  "message": "ReceivingDataJob scheduled"
}

Check status

Use this sample request to retrieve the status of the underlying processing job started by the commit.

Copy
cURL sample request: Check a commited transaction's job status
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions/0403f38d-7795-4df0-b805-ba3986761a4c' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the job status.

Copy 
{
  "tenantCode": "WFF_h1k",
  "transactionId": "0403f38d-7795-4df0-b805-ba3986761a4c",
  "jobId": "ef054370-c533-4574-bf96-59e0b75f33a2",
  "status": "RUNNING"
}

Roll back a transaction

Use this sample request to optionally roll back an uncommitted transaction. This endpoint removes all uploads in the transaction. After rolling back a transaction, the transaction ID cannot be used again.

Copy
cURL sample request: Roll back a pending transaction
curl -X DELETE --url 'https://{vanity_name}.api.visier.io/v1/data/directloads/prod/transactions/0403f38d-7795-4df0-b805-ba3986761a4c' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the rollback status.

Copy 
{
  "transactionId": "0403f38d-7795-4df0-b805-ba3986761a4c",
  "status": "ROLLED-BACK",
  "message": "Data transfer with transfer session id [ 0403f38d-7795-4df0-b805-ba3986761a4c ] canceled"
}