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

This example applies to all types of batch processes, ensuring consistency in handling bulk operations across different endpoints.

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": "[e-mail]",
            "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": "[e-mail]",
            "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
}