Data and Job Handling API Code Samples

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

Start the data load for analytic tenants

Use this sample request to start a data load for a specified tenant.

Copy
cURL sample request: Start a data load an analytic tenant
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/data/startload' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-d 'model={"files":["WFF_j1r_hcm_files_20181030102030.zip.gpg"]}'

The response returns details about the request's success. If successful, the response returns the generated job's jobId. If unsuccessful, the response returns a failure reason.

Run a processing job

Use this sample request to start a processing job and publish the new data version to production.

Note: Alpha This API is in alpha. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued. If you are interested in using this API, please contact your Customer Success Manager (CSM).

Copy
cURL sample request: Run a processing job and publish the data version to production
curl -X POST 'https://{vanity_name}.api.visier.io/v1alpha/op/jobs/processing-jobs' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
--data '{
    "dataCategoryId": "28f53042-1269-43b7-bfac-1placeholder",
    "publishToProduction": true
}'

The response returns the job's ID.

Run a data connector extraction job

Use this sample request to start an extraction job.

Note: Alpha This API is in alpha. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued. If you are interested in using this API, please contact your Customer Success Manager (CSM).

Copy
cURL sample request: Run an extraction job
curl -X POST 'https://{vanity_name}.api.visier.io/v1alpha/op/jobs/extraction-jobs' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
--data '{}'

The response returns the job's ID.

Retrieve a receiving job's status

Use this sample request to get a retrieving job's status.

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 details about the job, such as its status and parentJobId, if applicable.

Retrieve processing job statuses by receiving job ID

Use this sample request to get all the processing jobs associated with a receiving job.

Copy
cURL sample request: Retrieve the processing jobs associated with the 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 details about the receiving job's processing jobs, such as tenantCode, dataVersion, and status.

Retrieve the latest enabled data versions for all analytic tenants

Use this sample request to get all the latest enabled data versions for your analytic tenants.

Copy
cURL sample request: Get all the latest enabled data versions for all tenants
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/data-versions \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns each tenant's data version details, including the dataVersion number and dataVersionDate.

Copy
Sample response

    "tenants": [
        {
            "tenant": "WFF_j1r~i1o",
            "dataVersions": [
                {
                    "dataVersion": "123415",
                    "dataVersionDate": "2019-10-02T20:35:21.420Z"
                }, 
                {
                    "dataVersion": "121415",
                    "dataVersionDate": "2018-10-02T20:35:21.420Z"
                }
            ]
        }, 
        {
            "tenant": "WFF_j1r~c7o",
            "dataVersions": []
        }
    ],
    "limit": 1000,
    "start": 0 
}

Disable data versions for a list of analytic tenants

Use this sample request to disable specific data versions or the latest enabled data version for a list of tenants.

Copy
cURL sample request: Disable data version 5166161 for the tenant WFF_j1r~c7o and the latest enabled data version for WFF_j1r~e1a
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data-versions/disable \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d 'model=
    {
        "dataVersionObjects": [
            {
                "tenantCode": "WFF_j1r~c7o",
                "dataVersion": "5166161"
            },
            {
                "tenantCode”: “WFF_j1r~e1a"
            }
        ]
    }’

The response returns details about the request's success, including totalFailures, totalSuccess, and status.

Copy
Sample response
{
    totalFailures: 1,
    totalSuccess: 1,
    results: [
        {
            "jobId": "a3722f30-e02a-458d-8ce6-cbbcb36d0c0f",
            "dataVersion": "5166161",
            "tenantCode": "WFF_j1r~i1o",
            "status": "Succeeded",
            "message": ""
        },
        {
            "jobId": "",
                "dataVersion": "",
                "tenantCode": "WFF_j1r~c7o",
                "status": "Failed",
                "message": "There was no enabled data version for tenant WFF_j1r~c7o."
        }
    ]
}

Retrieve data uploads

Use this sample request to retrieve all tenants' data uploads.

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

The response returns details about each tenant's data uploads.

Copy
Sample response
{
    "tenants": [
        {
            "tenantCode": "WFF_j1r~i1o",
            "uploads": [{
                "uploadTime": "2019-10-08T20:35:21.420Z",
                "included": false
            }, {
                "uploadTime": "2019-10-09T20:35:21.420Z",
                "included": true
            }, {
                "uploadTime": "2019-10-10T20:35:21.420Z",
                "included": true
            },{
                "uploadTime": "2019-10-11T20:35:21.420Z",
                "included": true
            }, {
                "uploadTime": "2019-10-12T20:35:21.420Z",
                "included": true
            }]
        }, {
            "tenantCode": "WFF_j1r~c7o",
            "uploads": [{
                "uploadTime": "2019-10-12T20:35:21.420Z",
                "included": true
            }]
    }],
    "limit": 1000,
    "start": 0
}

Include data uploads

Use this sample request to include a specified list of data uploads.

Copy
cURL sample request: Include two data uploads for the tenant WFF_j1r~i1o and all data uploads for the tenant WFF_j1r~c7o
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data/uploads/include \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d model=
    {
        "uploads":[
            {
                "tenantCode": "WFF_j1r~i1o",
                "uploadTimes": [
                    "2019-10-12T20:35:21.420Z"
                    "2019-10-11T20:35:21.420Z"
                ]
            },{
                "tenantCode": "WFF_j1r~c7o"
                "includeAll": true
            }
        ]
    }'

The response returns details about the request's success, including totalFailures, totalSuccess, and uploads.

Copy
Sample response
{
    "totalFailures": 2,
    "totalSuccess": 1,
    "uploads": [{
        "tenantCode": "WFF_j1r~i1o",
        "uploadTime": "2019-10-12T20:35:21.420Z",
        "status": "Succeeded",
        "message": ""
     }, {
        "tenantCode": "WFF_j1r~i1o",
        "uploadTime": "2019-10-11T20:35:21.420Z",
        "status": "Failed",
        "message": "The data upload does not exist for the tenant."
    }, {
        "tenantCode": "WFF_j1r~c7o",
        "uploadTime": "2019-10-22T20:35:21.420Z",
        "status": "Failed",
        "message": "Insufficient permissions to access the specified tenant."
    }]
}

Exclude data uploads

Use this sample request to exclude a specified list of data uploads.

Copy
cURL sample request: Exclude two data uploads for the tenant WFF_j1r~i1o and all data uploads for the tenant WFF_j1r~c7o
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data/uploads/exclude \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d model=
    {
        "uploads":[
            {
                "tenantCode": "WFF_j1r~i1o",
                "uploadTimes": [
                    "2019-10-12T20:35:21.420Z"
                    "2019-10-11T20:35:21.420Z"
                ]
            },{
                "tenantCode": "WFF_j1r~c7o"
                "excludeAll": true
            }
        ]
    }'

The response returns details about the request's success, including totalFailures, totalSuccess, and uploads.

Copy
Sample response
{
    "totalFailures": 2,
    "totalSuccess": 1,
    "uploads": [{
        "tenantCode": "WFF_j1r~i1o",
        "uploadTime": "2019-10-12T20:35:21.420Z",
        "status": "Succeeded",
        "message": ""
     }, {
        "tenantCode": "WFF_j1r~i1o",
        "uploadTime": "2019-10-11T20:35:21.420Z",
        "status": "Failed",
        "message": "The data upload does not exist for the tenant."
    }, {
        "tenantCode": "WFF_j1r~c7o",
        "uploadTime": "2019-10-22T20:35:21.420Z",
        "status": "Failed",
        "message": "Insufficient permissions to access the specified tenant."
    }]
}

Cancel a list of jobs

Use this sample request to cancel a list of jobs by job ID.

Copy
cURL sample request: Cancel jobs 5571a6a5-6f72-44d8-b180-9508dfc81b89 and 1ec9fc64-9e2a-4dab-be98-86d6572a9281
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/cancel \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d model=
    {
        "jobIds":[
            "5571a6a5-6f72-44d8-b180-9508dfc81b89",
            "1ec9fc64-9e2a-4dab-be98-86d6572a9281"
        ]
    }'

The response returns the job cancellation results, including which jobs were successfully cancelled.

Copy
Sample response
{
    "jobCancellationResults": [{
        "tenantCode": "WFF_j1r~e1a",
        "jobId": "574beb98-d2bb-4038-b568-a97e13d0e032",
        "jobType": "PROCESSING_JOB",
        "parentJobId": "3ab09456-2aa0-4261-8ae8-a9669a62a260",
        "cancelStatus": "CANCEL_SUCCEEDED",
        "jobStatus": "Cancelled"
    }, {
        "tenantCode": "WFF_j1r",
        "jobId": "3ab09456-2aa0-4261-8ae8-a9669a62a260",
        "jobType": "UPLOAD_JOB",
        "jobStatus": "Succeeded",
        "message": "UploadJob [3ab09456-2aa0-4261-8ae8-a9669a62a260] with status [Succeeded] could not be cancelled."
    }, {
        "tenantCode": "WFF_j1r",
        "jobId": "ab3d49ee-fe0d-4636-9d81-ee7b1d64f67b",
        "jobType": "UPLOAD_JOB",
        "cancelStatus": "CANCEL_SUCCEEDED",
        "jobStatus": "Cancelled"
    }, {
        "tenantCode": "WFF_j1r",
        "jobId": "d9299c6a-287e-4ae5-9f34-edb3b4e91e37",
        "jobType": "UNRECOGNIZED",
        "message": "Unrecognized job [d9299c6a-287e-4ae5-9f34-edb3b4e91e37]."
    }]

}

Trigger data connector extraction jobs

Use this sample request to trigger extraction jobs for all tenants.

Copy
cURL sample request: Extract data for all tenants as of December 13, 2021 at midnight
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/data/startExtractAndLoad \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d model=
    {
        "allTenants": true,
        "overrideLastExtractionTimestamp": 1639382400000,
        "dataCategoryId": "a3e5ba0d-2413-4787-ae4f-ddc44fa9ce7a"
    }'

The response returns the jobId of the triggered extraction job.

Copy
Sample response
{
    "jobId": "bf944bf1-3120-44cd-846d-64cd88b295d9"
}

Retrieve a dispatching job's status

Use this sample request to get a specific dispatching job's status.

Copy
cURL sample request: Get the status of dispatching job 40bfd838-ad5f-40d9-9000-65c75bcf5f8b
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/dispatching-jobs/40bfd838-ad5f-40d9-9000-65c75bcf5f8b \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns details about the job.

Copy
Sample response
{
    "jobId": "bf944bf1-3120-44cd-846d-64cd88b295d9",
    "tenantCode": "WFF_j1r",
    "status": "Succeeded",
    "totalJobsDispatched": 5
}

Retrieve a dispatching job's extraction jobs with their statuses

Use this sample request to get a specific dispatching job's extraction jobs.

Copy
cURL sample request: Retrieve the extraction job statuses from the dispatching job with the ID 40bfd838-ad5f-40d9-9000-65c75bcf5f8b. Limit of 2, starting with the second tenant
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/dispatching-jobs/40bfd838-ad5f-40d9-9000-65c75bcf5f8b/extraction-jobs?limit=2&start=1 \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns details about the extraction jobs.

Copy
Sample response
{
    "parentJobId": "40bfd838-ad5f-40d9-9000-65c75bcf5f8b",
    "parentTenantCode": "WFF_j1r",
    "limit": 2,
    "start": 1,
    "extractionJobs": [{
        "extractionJobId": "36ac4635-5e40-4225-87bf-56e2a2b0a146",
        "tenantCode": "WFF_j1r~c7o",
        "status": "Succeeded",
    }, {
        "extractionJobId”": “4dfe8794-d3b0-40a7-bafc-cd2586a902c1",
        "tenantCode": "WFF_j1r~e1a",
        "status": "Running",
        "currentStage": "Process Records"
    }]
}

Retrieve a dispatching job's processing jobs with their statuses

Use this sample request to get a specific dispatching job's processing jobs.

Copy
cURL sample request: Retrieve the processing job statuses from the dispatching job with the ID 40bfd838-ad5f-40d9-9000-65c75bcf5f8b. Limit of 2, starting with the second tenant
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/dispatching-jobs/40bfd838-ad5f-40d9-9000-65c75bcf5f8b/processing-jobs?limit=2&start=1 \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns details about the extraction jobs.

Copy
Sample response
{
    "parentJobId": "40bfd838-ad5f-40d9-9000-65c75bcf5f8b",
    "parentTenantCode": "WFF_j1r",
    "limit": 2,
    "start": 1,
    "processingJobs": [{
        "jobId": "36ac4635-5e40-4225-87bf-56e2a2b0a146",
        "tenantCode": "WFF_j1r~c7o",
        "dataVersion": "7000013",
        "status": "Succeeded",
        "message": ""
    }, {
        "jobId": "4dfe8794-d3b0-40a7-bafc-cd2586a902c1",
        "tenantCode": "WFF_j1r~e1a",
        "dataVersion": "",
        "status": "Failed",
        "message": "[DP510002] Unexpected exception in data load process in the event stream loader stage. Please contact Visier Support."
    }]
}

Retrieve a dispatching job's receiving jobs with their statuses

Use this sample request to get a specific dispatching job's receiving jobs.

Copy
cURL sample request: Retrieve the receiving job statuses from the dispatching job with the ID 40bfd838-ad5f-40d9-9000-65c75bcf5f8b. Limit of 2, starting with the second tenant
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/jobs/dispatching-jobs/40bfd838-ad5f-40d9-9000-65c75bcf5f8b/receiving-jobs?limit=2&start=1 \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns details about the receiving jobs.

Copy
Sample response
{
    "parentJobId": "40bfd838-ad5f-40d9-9000-65c75bcf5f8b",
    "parentTenantCode": "WFF_j1r",
    "limit": 2,
    "start": 1,
    "receivingJobs": [{
        "receivingJobId": "36ac4635-5e40-4225-87bf-56e2a2b0a146",
        "tenantCode": "WFF_j1r~c7o",
        "status": "Succeeded"
    }, {
        "receivingJobId": "4dfe8794-d3b0-40a7-bafc-cd2586a902c1",
        "tenantCode": "WFF_j1r~e1a",
        "status": "Failed"
    }]
}

Retrieve a list of all data connectors

Use this sample request to get all data connectors in a specified tenant.

Copy
cURL sample request: Retrieve the data connectors for tenant WFF_j1r~c7o
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/data-connectors?tenantCode=WFF_j1r~c7o \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the connector ID, display name, and credential ID.

Copy
Sample response
{
    "dataConnectors": [{
        "connectorId": "36ac4635-5e40-4225-87bf-56e2a2b0a146",
        "displayName": "Redshift Jupiter",
        "credentialId": "d1dc6e91-e28f-4507-b9d5-0064b795d02a"
    }, {
        "connectorId": "4dfe8794-d3b0-40a7-bafc-cd2586a902c1",
        "displayName": "UKG Callisto",
        "credentialId": "d3607390-ab20-4619-97d8-9e33e7697430"
    }]
}

Retrieve a list of all data connector credentials

Use this sample request to get all data connector credentials in a specified tenant.

Copy
cURL sample request: Retrieve the data connector credentials for tenant WFF_j1r~c7o
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/op/data-connector-credentials?tenantCode=WFF_j1r~c7o \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the credential ID, display name, and data provider.

Copy
Sample response
{
    "connectorCredentials": [{
        "credentialId": "bf944bf1-3120-44cd-846d-64cd88b295d9",
        "displayName": "AWS S3 Jupiter",
        "dataProvider": "BasicS3",
        "isInherited": true
    }, {
        "credentialId": "bf27d5f8-e780-436f-b2dc-990ea52c91d3",
        "displayName": "Redshift Callisto",
        "dataProvider": "Redshift",
        "isInherited": true
    }]
}

Create a connector credential

Use this sample request to create a connector credential in a specified tenant.

Copy
cURL sample request: Create a UKG Pro connector credential in the WFF_j1r~e1a tenant
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/data-connector-credentials?tenantCode=WFF_j1r~e1a' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d model="{\"dataProviderAuthParams\":{\"provider\":\"UKG\",\"ultimateAuthParams\":{\"hostDomainName\":\"exampleHostDomain\",\"apiKey\":\"apiKey1234\",\"username\":\"username1234\",\"password\":\"password1234\",\"userAccessKey\":\"accessKey1234\"}},\"dataProviderBasicInformation\":{\"displayName\":\"exampleDisplayName\",\"description\":\"exampleDescription\"}}\""

The response returns the credential UUID, symbol name, and object name.

Copy
Sample response
{
    "uuid": "c850a6d9-4699-45b6-89f4-1c18f36fcfc4",
    "symbolName": "Extractor_Credential_Design_0",
    "objectName": "Extractor_Credential_Design_0"
}

Delete a connector credential

Use this sample request to delete a connector credential from a specified tenant.

Copy
cURL sample request: Create a credential in the tenant WFF_j1r~e1a
curl -X DELETE --url 'https://{vanity_name}.api.visier.io/v1/op/data-connector-credentials/bff2adb6-f772-49a5-ba64-b31dcc51ee61?tenantCode=WFF_j1r~e1a \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns a 200 OK if successful.

Assign connector credentials to data connectors

Use this sample request to assign a connector credential to a data connector.

Copy
cURL sample request: Assign connector credentials to a data connector in the tenants WFF_j1r~e1a and WFF_j1r~c7o
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/op/data-connectors/assignCredentials \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d '{"connectors"=:[{"connectorId":"cc8a7ddd-80c7-4645-8369-acbeea8cdfe5","tenants":[{"tenantCode":"WFF_j1r~e1a","credentialId":"5781eec0-7f1d-4d3b-b9bd-8c08ff632cfb"},{"tenantCode":"WFF_j1r~c7o","credentialId":"780ed445-3a58-4be6-8db1-038279b0c521"}]}]}'

The response returns the tenant code, the connector ID, and the assigned credential ID.

Copy
Sample response
{
    "tenants": [
        {
            "tenantCode": "WFF_j1r~e1a",
            "connectors": [
                {
                    "connector": {
                        "connectorId": "cc8a7ddd-80c7-4645-8369-acbeea8cdfe5",
                        "displayName": "Test Connector"
                    },
                    "credential": {
                        "credentialId": "5781eec0-7f1d-4d3b-b9bd-8c08ff632cfb",
                        "displayName": "Test Credential"
                    }
                }
            ],
            "status": "Succeed"
        },{
            "tenantCode": "WFF_j1r~c7o",
                "connectors": [
                    {
                        "connector": {
                            "connectorId": "4dfe8794-d3b0-40a7-bafc-cd2586a902c1",
                            "displayName": "Connector"
                        },
                        "credential": {
                            "credentialId": "780ed445-3a58-4be6-8db1-038279b0c521",
                            "displayName": "Credential"
                        }
                    }
                ],
                "status": "Succeed"
    ]
}

Retrieve data connector settings

Use this sample request to retrieve a list of all data connectors in the production environment and their settings.

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

The response returns all data connectors in your production environment and their available settings. In this example, there is one data connector called snowflakeconnector that has one setting called jdbcTenantCodeColumn.

Update data connector settings

Use this sample request to change the settings for one or more data connectors. In this example, we are updating the jdbcTenantCodeColumn setting in the WFF_j1r tenant to TenantID.

Copy
cURL sample request: Update the 46cf8c1c-705b-4593-8817-734b750df160 connector settings
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/op/data-connectors/connector-settings' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'
-d '{
    "connectors": [
      {
        "connectorId": "46cf8c1c-705b-4593-8817-734b750df160",
        "tenants": [
          {
            "tenantCode": "WFF_j1r",
            "connectorSettings": [
              {
                "settingKey": "jdbcTenantCodeColumn",
                "value": "TenantID"
              }
            ]
          }
        ]
      }
    ]
}

The response returns the connector and whether the settings update was successful.