Batch APIs usage example

The Batch Customer API allows you to create or update multiple customer profiles in a single request, optimizing performance and reducing network overhead. This is particularly useful for bulk user imports, mass profile updates, and large-scale customer data synchronization.​

Batch Customer API Tutorial

Overview

The Batch Customer API enables bulk creation or updates of customer profiles in a single request, optimizing performance and reducing API calls. This is useful for mass data synchronization, bulk user imports, and automated customer profile management.

Not

1. Create a Job request

Endpoint URL

POSThttps://api.gameball.co/api/v4/integrations/batch/customers

This endpoint processes multiple customer records in one request.

Authentication

Include your API key in the request headers:

ApiKey: YOUR_API_KEY
SecretKey: YOUR_SECRET_KEY
Content-Type: application/json  

Request Structure

The request body must contain an array of customer objects, each with relevant attributes.

Example Request

{
    "body": [
        {
            "customerId": "12345",
            "email": "[email protected]",
            "name": "John Doe",
            "gender": "M",
            "dateOfBirth": "1990-01-01",
            "joinDate": "2022-01-01",
            "tags": [
                "vip",
                "newsletter_subscriber"
            ],
            "custom": {
                "favorite_color": "blue",
                "loyalty_points": 1500
            }
        },
        {
            "customerId": "67890",
            "email": "[email protected]",
            "name": "Jane Smith",
            "gender": "F",
            "dateOfBirth": "1985-05-15",
            "joinDate": "2023-03-10",
            "tags": [
                "premium_member"
            ],
            "custom": {
                "favorite_color": "green",
                "loyalty_points": 2000
            }
        }
    ]
}

Response Structure

The response contains the JobId of the created job to check the status for, get the response, or terminate the job.

Example Response

{
    "jobId": 123456
}

2. Get the Job status

Endpoint URL

GEThttps://api.gameball.co/api/v4/integrations/batch/{jobId}

Authentication

Include your API key in the request headers:

ApiKey: YOUR_API_KEY
SecretKey: YOUR_SECRET_KEY
Content-Type: application/json 

Response Structure

Queued
{
  "operation": "Customer Creation Batch Job",
  "errorCount": 0,
  "totalCount": 0,
  "finishedCount": 0,
  "startedAt": null,
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "queued",
  "response": null
}
Running
{
  "operation": "Customer Creation Batch Job",
  "errorCount": 0,
  "totalCount": 1,
  "finishedCount": 1,
  "startedAt": "2025-03-14T10:30:00Z",
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "running",
  "response": {
    "successful": [
      {
        "customerId": "12345",
        "message": "Customer created successfully"
      }
    ],
    "failed": []
  }
}
Completed
{
  "operation": "Customer Creation Batch Job",
  "errorCount": 1,
  "totalCount": 2,
  "finishedCount": 1,
  "startedAt": "2025-03-14T10:00:00Z",
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "completed",
  "response": {
    "successful": [
      {
        "customerId": "12345",
        "message": "Customer created successfully"
      }
    ],
    "failed": [
      {
        "customerId": "67890",
        "error": "Failed to create customer"
      }
    ]
  }
}
Failed
{
  "operation": "Customer Creation Batch Job",
  "errorCount": 2,
  "totalCount": 2,
  "finishedCount": 0,
  "startedAt": null,
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "failed",
  "response": {
    "successful": [],
    "failed": [
    {
        "customerId": "12345",
        "message": "Failed to create customer"
      },
      {
        "customerId": "67890",
        "error": "Failed to create customer"
      }
    ]
  }
}
Stopped
{
  "operation": "Customer Creation Batch Job",
  "errorCount": 0,
  "totalCount": 0,
  "finishedCount": 0,
  "startedAt": null,
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "stopped",
  "response": null
}

3. Stop the running Job

Endpoint URL

DELETEhttps://api.gameball.co/api/v4/integrations/batch/{jobId}

Authentication

Include your API key in the request headers:

ApiKey: YOUR_API_KEY
SecretKey: YOUR_SECRET_KEY
Content-Type: application/json 

Response

200 - Ok: Job stopped successfully

If we go back to step 2 and check the job status, we'd get the following result

{
  "operation": "Customer Creation Batch Job",
  "errorCount": 0,
  "totalCount": 0,
  "finishedCount": 0,
  "startedAt": null,
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "stopped",
  "response": null
}

Last updated