Get bulk update job details

When to use this

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

getBulkUpdateShown in the dashboard as “Get Bulk Update History”

This endpoint needs getBulkUpdate, shown in the dashboard as Get Bulk Update History. Use a Community API key and keep it on your server. The key decides the community, so you can only read jobs from that community.

02Behaviour#

03Request#

Path parameters#

Query parameters#

Headers#

curl --request GET \
  --url 'https://api.returning.ai/v1/users/bulk-update/66f000000000000000000701/details?page=1&limit=100' \
  --header 'Authorization: Bearer <API_KEY>'

04Response#

Each row is one line of your file, with status and errors added. The cells come back as strings, keyed by the lower-case column name. The standard columns use short keys: Email is email, First Name is firstname, Last Name is lastname, Phone Number is phone, Role is roles, Tag is tags, Total XP is xp and Total Coins is coin. Operator and custom field columns are lower-cased, such as total coins_op and kyc status.

A failed row lists its reasons in errors. Branch on code:

• USER_NOT_AVAILABLE: no trader in your community matches the row's email or identifier.
• USER_NOT_COMMUNITY_MEMBER: the account exists but is not a member of your community.
• REQUIRED_VALUE: the Email cell, or the identifier cell, is empty.
• DUPLICATE_VALUE: an earlier row in the file has the same email or identifier. Only the first row is applied.
• IDENTIFIER_CONFLICT: the trader already has a different broker customer ID, or another trader has this one.
• IDENTIFIER_LOOKUP_UNAVAILABLE: lookup by identifier wasn't available. Upload the row again later.
• INVALID_OPERATOR: an _op cell is not add, subtract or overwrite.
• INVALID_VALUE: a cell failed its check, for example an unknown role, tag or badge, text in a number column, a badly formatted date, or an unknown country or language.
• ROW_OUTCOME_UNCERTAIN: the coin change couldn't be checked against your community's rule that traders must visit before earning coins, so the row was not applied. Upload it again later.
• BULK_ROW_FAILED: any other failure, for example a trader who hasn't visited your community yet when that rule is on.

Before you upload a failed row again, read the trader back: an error while saving can leave part of a row applied. An ID that matches no job in your community returns 200 with zero counts and no data list, not 404.

{
  "status": "success",
  "message": "Bulk update details fetched successfully",
  "data": {
    "successUsers": 1,
    "failedUsers": 1,
    "pagination": {
      "total": 2,
      "currentPage": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    },
    "data": [
      {
        "email": "trader@example.com",
        "coin": "500",
        "total coins_op": "add",
        "kyc status": "verified",
        "status": "success",
        "errors": []
      },
      {
        "email": "no.account@example.com",
        "coin": "500",
        "total coins_op": "add",
        "kyc status": "verified",
        "status": "failed",
        "errors": [
          {
            "field": "email",
            "code": "USER_NOT_AVAILABLE",
            "message": "User was not found in the target community"
          }
        ]
      }
    ]
  }
}

05Errors#

{
  "status": "fail",
  "message": "Bulk update ID is required and must be a valid ObjectId"
}

06Next step#