Data Intake API Code Samples

Selection of code samples that demonstrate the use of the 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 "Data Intake" in API Reference.

Retrieve a list of sources

Use this sample request to retrieve all the sources in your Visier tenant. The returned sources are the sources you can load data into using the Data Intake API.

Copy
cURL sample request: Retrieve all sources
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/data-sources' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns all the sources in the tenant.

Copy 
{
    "sources": [
        {
            "sourceId": "3fc392f9-1af3-49c1-a80b-4cc31b9d6609", 
            "name": "Compensation_Budgeted",
            "columns": [
                {
                    "columnName": "TenantCode", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "EventDate", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "EmployeeID", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "Attribute", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "Value", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                } ],
            "isInherited": true 
        },
        {
            "sourceId": "4cfa10e5-4a9a-45a3-930a-35ed8004a7fc", 
            "name": "Employee_Starts",
            "columns": [
                {
                    "columnName": "TenantCode", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "EffectiveDate", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "EmployeeID", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "HireType", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                }, {
                    "columnName": "Action", 
                    "dataType": "TEXT", 
                    "isMandatory": true, 
                    "allowEmpty": true
                } ],
        "isInherited": true 
    }
]

Note:  

  • All fields specify the required data type and name. For example, Employee_Starts has a field called EmployeeID. Its data type must be TEXT and it must contain a value in the data file. If you try to load Employee_Starts without a field called Employee-ID, it will fail.
  • Fields with "dataType": "DATE" specify acceptable date formats.
  • "isMandatory": true indicates the field must contain a value. If a mandatory field is empty, the data load will fail.
  • "allowEmpty": true indicates the value is optional and may be empty.

Start a transfer session

Use this sample request to start a new transfer session.

Copy
cURL sample request: Start a transfer session
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/data-transfer-sessions' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the transfer session ID, which you'll use in later requests to send data to Visier.

Copy 
{
    "transferSessionId": "03898114-6854-4448-b41a-adb8038e9792"
}

Transfer data to sources via JSON

Use this sample request to send data to a source in Visier through a JSON payload. Alternatively, you can send data to Visier through file upload. For more information, see Transfer data to sources via file upload.

Note:  

  • Each request includes a batch of records formatted as a comma separated array with the first row containing the column headers in the request body. Each subsequent request should also include the first row as a header.
  • Each request transfers a batch of records to a single source. Transfer sessions may include one or more batches before completion.
  • Each batch is identified by a sequence number. Sequence numbers help identify any batches that were delivered incorrectly.
  • Data limits:
    • Batch size limit: 10 MB
    • Record count limit: 300,000 rows
Copy
cURL sample request: Transfer data to source 6a351160-b631-46e5-8321-1540b3dffde2 through JSON
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data-transfer-sessions/03898114-6854-4448-b41a-adb8038e9792/add?source_id=6a351160-b631-46e5-8321-1540b3dffde2&sequence=1&tenantcode=WFF_j1r~c7o' \
-H "apikey:12345" \
-H "Cookie:VisierASIDToken=abc123" \
-H "Content-Type: application/json" -d '\
    [
        "TenantCode, EffectiveDate, EmployeeID, HireType, Action", \
        "WFF_j1r~c7o,2016-07-13 00:00:00,2668899,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-16 00:00:00,2668900,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-07-14 00:00:00,2668900,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-14 00:00:00,2668902,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-07-13 00:00:00,2668902,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2017-05-15 00:00:00,2668902,JOB DESCRIPTION,ADVOCATE-ORDER ENTRY", \
        "WFF_j1r~c7o,2017-08-16 00:00:00,2668902,JOB DESCRIPTION,ADVOCATE-ORDER ENTRY", \
        "WFF_j1r~c7o,2016-06-23 00:00:00,2668936,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-07-14 00:00:00,2668936,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-10 00:00:00,2668940,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-13 00:00:00,2668940,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-07-13 00:00:00,2668940,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-10 00:00:00,2668943,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-07-14 00:00:00,2668943,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2017-05-30 00:00:00,2668943,JOB DESCRIPTION,ASSOC-FULFILLMENT CENTER", \
        "WFF_j1r~c7o,2016-06-10 00:00:00,2669257,JOB DESCRIPTION,SPECIALIST-PRODUCTION"
    ]

The response returns whether or not the transfer was successful.

Copy 
{
    "transferSessionId": "f561aadc-6a0e-4e67-b2e5-e2daeffd735d", 
    "sequence": 1,
    "status": "SUCCEED",
    "tenants": [
        {
            "tenantCode": "WFF_j1r~c7o", 
            "status": "SUCCEED", 
            "sources": [
                {
                    "sourceId": "6a351160-b631-46e5-8321-1540b3dffde2",
                    "sourceName": "Employee_Profile",
                    "dataSize": "1364",
                    "rows": "16",
                    "status": "SUCCEED",
                    "message": "Processed [WFF_j1r~c7o] [6a351160-b631-46e5-8321-1540b3dffde2] data"
                }, {
                    "sourceId": "4cfa10e5-4a9a-45a3-930a-35ed8004a7fc", "sourceName": "Employee_Starts",
                    "dataSize": "849",
                    "rows": "16",
                    "status": "SUCCEED",
                    "message": "Processed [WFF_j1r~c7o] [4cfa10e5-4a9a-45a3-930a-35ed8004a7fc] data" 
                }
            ] 
        }
    ] 
}

Transfer data to sources via file upload

Use this sample request to send data to Visier through a file upload. Alternatively, you can send data to Visier through a JSON paylod. For more information, see Transfer data to sources via JSON.

Note:  

  • Each request transfers a single file. If the data intended for Visier is stored in multiple files, you may compress them into a single ZIP file or make multiple requests within the same transfer session.
  • If you define a specific source in the request, all files within the request will target the declared source. If a source is not defined, the filenames are matched against the source regex to correctly assign each file to a source. If you include files that should target multiple sources in one ZIP file, do not define a source in the request.
  • Each batch is identified by a sequence number. Sequence numbers help identify any batches that were delivered incorrectly.
  • Data limits:
    • File size limit: 3 GB
    • Files: One ZIP file per source
Copy
cURL sample request: Upload a ZIP file for source 6a351160-b631-46e5-8321-1540b3dffde2
curl -X PUT \
-F file=@file.zip;type=application/zip \
--url 'https://{vanity_name}.api.visier.io/v1/op/data-transfer-sessions/3b43817a-d0de-4dec-ae94-5467ddea5b83/upload?source_id=6a351160-b631-46e5-8321-1540b3dffde2&sequence=1&tenantcode=WFF_j1r~c7o' \
-H "apikey:12345" -H "Cookie:VisierASIDToken=abc123"

The response returns the upload status.

Copy 
{
    "transferSessionId": "f561aadc-6a0e-4e67-b2e5-e2daeffd735d", 
    "sequence": 1,
    "status": "SUCCEED",
    "tenants": [
        {
            "tenantCode": "WFF_j1r~c7o", 
            "status": "SUCCEED", 
            "sources": [
                {
                    "sourceId": "6a351160-b631-46e5-8321-1540b3dffde2",
                    "sourceName": "Employee_Profile",
                    "dataSize": "1364",
                    "rows": "0",
                    "status": "SUCCEED",
                    "message": "Processed [WFF_j1r~c7o] [6a351160-b631-46e5-8321-1540b3dffde2] data"
                } 
            ]
        } 
    ]
}

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

Copy
cURL sample request: Upload a CSV file to the same transfer session as the previous request
curl -X PUT \
-F file=@file.csv;type=text/csv \
--url 'https://{vanity_name}.api.visier.io/v1/op/data-transfer-sessions/3b43817a-d0de-4dec-ae94-5467ddea5b83/upload?source_id=4cfa10e5-4a9a-45a3-930a-35ed8004a7fc&sequence=2&tenantcode=WFF_j1r~c7o' \
-H "apikey:12345" -H "Cookie:VisierASIDToken=abc123"

Complete a transfer session

Use this sample request to complete a transfer session. This endpoint initiates loading all the JSON data or uploaded files within the transfer session by starting a receiving job. After completing a transfer session, you cannot upload additional data to the session.

Note: You can optionally use the processingData field to generate a data version. If true, a processing job automatically begins after the receiving job completes. A successful processing job generates a new data version. If false, you must run a job separately to generate a data version. For more information about data versions, see Data Versions.

Copy
cURL sample request: Complete a transfer session
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/receiving-jobs' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token} -d '
    {
        "transferSessionId": "3b43817a-d0de-4dec-ae94-5467ddea5b83", 
        "processingData": true
    }

The response returns the receiving job ID and results of the data transfer.

Copy 
{
    "dataReceivingJobId": "ae3ea8fa-6dbe-4fa8-ab47-6c7f834e6258", 
    "message": "ReceivingDataJob scheduled",
    "transferSessionId": "f561aadc-6a0e-4e67-b2e5-e2daeffd735d", 
    "dataTransferResultDetails": [
        {
            "tenantCode": "WFF_j1r~c7o", 
            "sourceNames": [
                "Employee_Profile",
                "Employee_Starts"
            ],
            "dataSize": "2213", 
            "rows": "32"
        }, {
            "tenantCode": "WFF_j1r~i1o", "sourceNames": [
                "Employee_Profile",
                "Employe_Starts"
            ],
            "dataSize": "2838",
            "rows": "39" 
        }
    ],
    "status": "SUCCEED" 
}

Cancel a transfer session

Use this sample request to cancel a transfer session.

Copy
cURL sample request: Cancel session 3b43817a-d0de-4dec-ae94-5467ddea5b83
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data-transfer-sessions/3b43817a-d0de-4dec-ae94-5467ddea5b83/cancel' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json'

The response returns the cancellation result.

Copy 
{
    "message": "Data transfer with transfer session id [ 90b40f5a-d3fc-4be6-91d7-0b8795699244 ] cancelled", "transferSessionId": "90b40f5a-d3fc-4be6-91d7-0b8795699244",
    "dataTransferResultDetails": [
        {
            "tenantCode": "WFF_j1r~c7o", 
            "sourceNames": [
                "Employee_Profile",
                "Employee_Starts"
            ],
            "dataSize": "2213", 
            "rows": "32"
        }, {
            "tenantCode": "WFF_j1r~i1o", 
            "sourceNames": [
                "Employee_Profile",
                "Employee_Starts"
            ],
            "dataSize": "2838", 
            "rows": "39"
        }
    ],
    "status": "CANCELLED" 
}

Retrieve a receiving job's status

Use this sample request to retrieve the status of the receiving job that begins after completing a transfer session.

Copy
cURL sample request: Retrieve the status of job 3b43817a-d0de-4dec-ae94-5467ddea5b83
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/receiving-jobs/3b43817a-d0de-4dec-ae94-5467ddea5b83' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the job status.

Copy 
{
 "JobId": "1ff19c84-1daa-4ef2-b232-02a617a20dfc", 
 "Status": "Succeed"
}

Retrieve processing job statuses by receiving job ID

Use this sample request to retrieve the status of the processing jobs associated with a receiving job.

Copy
cURL sample request: Retrieve the processing job statuses from receiving job 3b43817a-d0de-4dec-ae94-5467ddea5b83
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/processing-jobs/3b43817a-d0de-4dec-ae94-5467ddea5b83' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the job statuses.

Copy 
{
    "parentJobId": "3b43817a-d0de-4dec-ae94-5467ddea5b83", 
    "parentTenantCode": "WFF_j1r",
    "limit": 1000,
    "start": 0,
    "processingJobs": [
        {
            "jobId": "479d1564-39bb-4337-b8f9-0fea11261815", 
            "tenantCode": "WFF_j1r~i1o",
            "dataVersion": "7000013",
            "status": "Rescheduled",
            "message": ""
        }, {
            "jobId": "62f43bf9-58a1-44eb-93dd-72b91e63f46a", 
            "tenantCode": "WFF_j1r~i1o",
            "dataVersion": "7000013",
            "status": "Cancelled",
            "message": "" 
        },{
            "jobId": "ef9363ba-d528-4faa-828a-3b4d2f400b4b", 
            "tenantCode": "WFF_j1r~c7o",
            "dataVersion": "7000014",
            "status": "Rescheduled",
            "message": ""
        }, {
            "jobId": "9fe92f66-765e-4d35-94f1-43fc1298c712", 
            "tenantCode": "WFF_j1r~c7o",
            "dataVersion": "7000014",
            "status": "Running",
            "message": "" 
        }
    ] 
}