Skip to main content
Use this endpoint to create multiple users within your project in a single request. Users are scoped to both the project and workspace mode (TEST or LIVE).
POST
https://api.taag.cc/v1/users/create/batch

​
Authorization

All you need is to include your secret key as a value of authorization in the header and hit the endpoint above. 
Authorization: taag_sk_mode_xxxxxxxxx
​
Authorization
string
required
Use the secret key that matches the mode you are in TEST or LIVE

​
Request Body

Provide an array of users to create. Each user object should contain an email and optionally a name and country code. 
{
  "users": [
    {
      "email": "[email protected]",
      "name": "John Doe",
      "countryCode": "US"
    },
    {
      "email": "[email protected]",
      "name": "Jane Smith",
      "countryCode": "GB"
    },
    {
      "email": "[email protected]",
      "countryCode": "FR"
    }
  ]
}
​
users
array
required
An array of user objects to create. Minimum 1 user, maximum 1000 users per request.
​
users[].email
string
required
The email address of the user. Must be a valid email format.
​
users[].name
string
The name of the user (optional)
​
users[].countryCode
string
A 2-letter ISO country code (e.g., “US”, “GB”, “FR”). Must be uppercase or will be converted to uppercase.
  • Users are unique per project and mode combination. The same email can exist in both TEST and LIVE modes.
  • Duplicate emails within the same request will be rejected.
  • If some users already exist or are invalid, the operation will continue and create the valid, non-duplicate users.

​
Response

The response includes a summary of the batch operation and details about any issues encountered.

​
Successful

{
  "success": true,
  "message": "Successfully created all 3 users",
  "summary": {
    "totalRequested": 3,
    "totalCreated": 3,
    "totalAlreadyExisted": 0,
    "totalInvalid": 0,
    "totalProcessed": 3
  }
}

​
Partial Success Response (Some Issues)

When some users already exist or have validation errors, you’ll receive a 207 Multi-Status response: 
{
  "success": true,
  "message": "Batch operation completed: 2 created, 1 already existed, 0 invalid",
  "summary": {
    "totalRequested": 3,
    "totalCreated": 2,
    "totalAlreadyExisted": 1,
    "totalInvalid": 0,
    "totalProcessed": 3
  },
  "issues": [
    {
      "email": "[email protected]",
      "status": "already_exists",
      "error": "User with this email already exists in this project",
      "data": {
        "userId": "ext_abc123",
        "email": "[email protected]",
        "name": "John Doe",
        "countryCode": "US",
        "mode": "TEST",
        "createdAt": "2025-12-10T08:30:00.000Z"
      }
    }
  ]
}

​
Error Responses

Returned when the request body is missing or empty.
{
    "success": false, 
    "error": "Missing request body", 
    "description": "Request body is required with users array" 
}
Returned when the users array is missing or not an array.
{
    "success": false, 
    "error": "Invalid request format", 
    "description": "Request body must contain a 'users' array" 
}
Returned when the users array is empty.
{
    "success": false, 
    "error": "Empty users array", 
    "description": "The users array must contain at least one user" 
}
Returned when the request contains more than 1000 users.
{
    "success": false, 
    "error": "Too many users", 
    "description": "Maximum 1000 users can be created in a single batch request" 
}
Returned when the request body contains malformed JSON.
{
    "success": false, 
    "error": "Invalid JSON", 
    "description": "The request body contains invalid JSON. Please check for syntax errors like trailing commas or missing quotes." 
}
Returned when some users have validation errors. The response includes which users failed and why.
{
    "success": true, 
    "message": "Batch operation completed: 1 created, 0 already existed, 2 invalid", 
    "summary": { 
        "totalRequested": 3, 
        "totalCreated": 1, 
        "totalAlreadyExisted": 0, 
        "totalInvalid": 2, 
        "totalProcessed": 3 
    }, 
    "issues": [ 
        { 
            "email": "invalid-email", 
            "status": "invalid", 
            "error": "Invalid email format" 
        }, 
        { 
            "email": "[email protected]", 
            "status": "invalid", 
            "error": "Country code must be a 2-letter code (e.g., "US", "GB", "FR")" 
        } 
    ] 
}
Returned when an unexpected error occurs.
{
    "success": false, 
    "error": "Internal Server Error", 
    "description": "An unexpected error occurred while creating project users. Please try again or contact support if the issue persists." 
}

​
Issue Status Types

When issues are reported in the response, they will have one of the following statuses:
  • already_exists: A user with this email already exists in the project for the current mode. The existing user’s data is included in the response.
  • invalid: The user data failed validation (e.g., invalid email format, invalid country code, duplicate in request, missing email).