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

1
2
3
4
5
6
7
8
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

1
2
3
4
5
6
7
8
9
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

1
2
3
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.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "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

1
2
3
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.

View sample response

Copy

1
2
3
{
  "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

1
2
3
4
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.

View sample response

Copy

1
2
3
4
{
  "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

1
2
3
4
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

1
2
3
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.

View sample response

Copy

1
2
3
4
5
{
  "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

1
2
3
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.

View sample response

Copy

1
2
3
4
5
6
{
  "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

1
2
3
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.

View sample response

Copy

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