Bulk user management endpoints

The bulk management API endpoints let you create or update a large number of users through the bulk user management collection.

The API supports the use of JSON files. You can get JSON data using the template API.

Only api_user authentication is supported. You must enter the API user token in the password variable. The legacy authentication using a company secret is not supported.

When a JSON file is uploaded through the upload API, a job is created and validates the json file scheme.

The endpoints supported for bulk user management include the following:

To perform bulk user addition or updates using the bulk user API, do the following:

  1. Call the Template method to get the JSON template object that you will use to generate the JSON file.

  2. Call either the Bulk add users from file method or the Bulk update users from file method, depending on whether you are doing a bulk add or a bulk update. This verifies the schema of JSON file that you provide.

  3. After the JSON file schema is verified, call the Proceed method. This starts the job.

  4. To determine the status of the job, call the Jobs method.

JSON file format

You can get the JSON file format by calling the template method.

Field(s) name Values Required Validation
email String(Email) Yes Must be a valid email. Must be unique within the file within Email column (no duplicates). so only 1 update per email address per file
new_email String(Email) No Must be a valid email. Must be unique within the file within New Email column (no duplicates). so only 1 update per email address per file
agent_number String No A string with no validation
first_name String Yes Non-empty string
last_name String Yes Non-empty string
status Active, Inactive, Empty No Must be "Active", "Inactive", or empty
location A string that is a location name, Empty, Null No Must exactly match one of the existing locations (case-insensitive), or Null, or empty
max_chat_limit 1 to X (where X is configured value), Empty No Must be 1 to X (inclusively), or empty
max_chat_limit_enabled 0, 1, Empty No Must be 0, 1 or empty
roles name: Role name / value: 0, 1, Empty No Must be 0, 1 or empty
teams name: Team name / value: 0, 1, Empty No Must be 0, 1 or empty

Once the JSON file upload API method is successful, the Proceed API method can be called, and user creation or modification work is then processed.

The upload and proceed methods are asynchronously performed by CCAI Platform. You can check status by calling the jobs method and specifying job_id.

Status field

The job status field can have any of the following values:

Job status Description
created A job is created and waiting for validation.
valid_scheme Scheme validation is successful and proceed is possible.
invalid_scheme Scheme validation failed. Detailed information can be checked through the Scheme error log API.
in_progress Performing bulk user update/create.
finished Bulk user update/create complete.

Template

Endpoint:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

Example request and responses

The following sections provide example requests to the endpoint.

Get template

This example demonstrates how to retrieve the templates.

Request

Body: None

Response: Template
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

Status Code: 200

Jobs

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

Example request and responses

The following sections provide example requests to the endpoint.

Job detail

This example demonstrates how to retrieve the job detail for a specific job. In this example, the job ID is 1.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job detail
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Status Code: 200

Job list

This example demonstrates how to get all jobs.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Response: Job list
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

Status Code: 200

Job created

This example demonstrates how to retrieve the bulk user request jobs that have been created.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job created
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Status Code: 200

Job validating success

This example demonstrates how to validate that a job is successful.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job validating success
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Status Code: 200

Job validating fails

This example demonstrates how to determaine that a job that has failed.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job validating fails
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

Status Code: 200

Job updating

This example demonstrates how to determine that a job that is updating.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job updating
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Status Code: 200

Job update finish without errors

In this example we show how to identify a job that is finished without errors.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job update finish without errors
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Status Code: 200

Job update finish with errors

In this example we show how to identify a job that has finished with errors.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Job update finish with errors
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

Status Code: 200

Error: Invalid job ID

This example shows a failure request where the job ID is invalid.

Request

Headers:

Key Value Description
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Response: Error: Invalid job ID
{
    "message": "Not Found"
}

Status Code: 404

Bulk add users from file

Headers:

Key Value Description
Content-Type multipart/form-data

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

Body:

Key Value Description
file

Example request and responses

The following sections provide example requests to the endpoint.

Job created

This example shows how to submit a job.

Request

Body:

Key Value Description
file
Response: Job created
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Status Code: 200

Bulk update users from file

Endpoint:

Method: PUT
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

Headers:

Key Value Description
Content-Type multipart/form-data

Body:

Key Value Description
file

Example request and responses

The following sections provide example requests to the endpoint.

Upload contacts file

This example shows how to update contacts using a file.

Request

Headers:

Key Value Description
Content-Type multipart/form-data

Body:

Key Value Description
file
Response Job created
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Status Code: 200

Proceed

This API endpoint is used to continue an ipport job that has been started.

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

Headers:

Key Value Description
Content-Type multipart/form-data

Body:

Key Value Description
id `[job_id}`

Example request and responses

The following sections provide example requests to the endpoint.

Proceed success

This example shows a job proceed that is successful.

Request

Headers:

Key Value Description
Content-Type multipart/form-data

Query:

Key Value Description
id `[job_id}`
Response: Proceed success
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Status Code: 200

Error: Proceed when before validation

This example shows a proceed prior to validation being completed.

Request

Headers:

Key Value Description
Content-Type multipart/form-data

Query:

Key Value Description
id `[job_id}`
Response: Error: Proceed when before validation
{
    "message": "This job cannot proceed update. status: created"
}

Status Code: 400

Error: Proceed when in progress

This example shows a proceed when the job is already in process.

Request

Headers:

Key Value Description
Content-Type multipart/form-data

Query:

Key Value Description
id `[job_id}`
Response: Error: Proceed when in progress
{
    "message": "Update is already in progress."
}

Status Code: 400

Scheme errors

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

Example request and responses

The following sections provide example requests to the endpoint.

Scheme errors

This example shows how to retrieve the schema errors.

Request

Body: None

Response: Scheme errors
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Status Code: 200

No errors

This example showes how to retrieve the schema errors with no errors.

Request

Body: None

Response: No errors
[]

Status Code: 200

Update errors

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

Example request and responses

The following sections provide example requests to the endpoint.

Update errors

This example shows how to retrieve the schema errors with update errors.

Request

Body: None

Response: Update errors
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

Status Code: 200

No errors

This example shows how to retrieve the schema errors with no errors.

Request

Body: None

Response: No errors
[]

Status Code: 200