Clients

Use these methods to manage client profiles and obtain client-related data.

GET[host]/api/v2/clients

Get a client list

GET[host]/api/v2/clients/{clientId}

Get client details

POST[host]/api/v2/clients

Create a client profile

PATCH[host]/api/v2/clients/{clientId}

Update a client profile

DELETE[host]/api/v2/clients/{clientId}

Remove a client profile

Get a client list

Use this method to get a list of the clients registered in the Back Office.

Note

If such a request is made by an admin user that is only permitted to view clients with certain tags, a response includes only the list of clients marked with these tags.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Query parameters:

The following filter parameters are available for this method:

clientId

The client identifier.

email

The client email address.

name

The client name.

nickname

The client nickname.

managerIds

A comma-separated list of integer values identifying the client managers.

countryCodes

The numeric code of a client’s country of residence (as per ISO 3166).

city

The client’s city.

statusIds

A comma-separated list of integer values identifying the client profile statuses.

internalTypeIds

A comma-separated list of integer values identifying the internal categories assigned to clients.

companyShortName

The client company short name.

companyFullName

The client company full name.

riskLevelIds

A comma-separated list of integer values identifying the client risk levels.

typeIds

A comma-separated list of integer values identifying the categories assigned to clients (such as Individual or Corporate).

verificationLevelIds

A comma-separated list of integer values identifying the verification levels obtained by clients.

Refer to the Query parameters section in the API Overview for details on applying filter parameters.

GET[host]/api/v2/clients

curl --location -g --request GET 'https://host.name/api/v2/clients?limit=10&offset=0&sort_order=desc&sort_by=createTime&filter[clientId]=1&filter[emails]=foo@bar.com&filter[name]=Sergey&filter[nickname]=Voronov&filter[managerIds]=1, 2, 3&filter[countryCodes]=1, 2, 3&filter[city]=New York&filter[statusIds]=1, 2, 3&filter[internalTypeIds]=1, 2, 3&filter[companyShortName]=Company name&filter[companyFullName]=Company full name&filter[riskLevelIds]=1, 2, 3&filter[typeIds]=1, 2, 3&filter[verificationLevelIds]=-96750485' \
--header 'Authorization: Bearer <token>'

Response

A response includes an array of Client objects providing information about the clients matching the request parameters.

Get client details

Use this method to obtain detailed information about a specified client.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Path parameters:

clientId required

The client identifier.

GET[host]/api/v2/clients/{clientId}

curl --location --request GET 'https://host.name/api/v2/clients/1' \
--header 'Authorization: Bearer <token>'

Response

A response contains a Client object providing information about the specified client.

Create a client profile

Use this method to register a new client and create a client profile.

Request

Header parameters:

  • Authorization: Bearer <token>

Body:

Important

The parameters that must be specified for a new client profile depend on the Registration wizard configuration.

To view the wizard configuration, navigate to System > Wizards in the Back Office, and then find a wizard of the registration type in a list.

The parameters listed below are for illustration purposes.

info object

The object specifying client personal data.

Show object fields
givenName string

The client’s first name.

familyName string

The client’s last name.

middleName string

The client’s middle name.

birthday string

The client’s date of birth.

addresses object

The object specifying a numeric country code indicating a client’s location.

Show object fields
country_code string

The numeric code of a country.

phones object

The object specifying one or several client phone numbers.

Show object fields
phone string

The client phone number.

email string

The email address used by a client to sign in to the B2Core UI.

POST[host]/api/v2/clients

curl --location --request POST 'https://host.name/api/v2/clients' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "info": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "addresses": {
    "0": {
      "country_code": "784"
    }
  },
  "phones": {
    "0": {
      "phone": "+971000000000"
    }
  },
  "email": "jdoe@example.com"
}'

Response

A response includes a Client object providing information about the created client profile.

Update a client profile

Use this method to update client profile data.

Request

Header parameters:

  • Authorization: Bearer <token>

Path parameters:

clientID required

The client identifier.

Body:

The following field values can be updated:

tfaProvidersForDisable array

An array of string values specifying the 2FA methods that you want to disable for a client. Possible values:

  • sms — SMS codes

  • google — the Google Authenticator app

givenName string

The client’s first name.

familyName string

The client’s last name.

middleName string

The client’s middle name.

birthday string

The client’s date of birth.

maxAccountsDemo integer

The maximum number of demo trading accounts that a client can open.

maxAccountsTrade integer

The maximum number of live trading accounts that a client can open.

sex integer

The client gender. Possible values:

  • 1 — male

  • 2 — female

  • 3 — undefined

countryCode integer

The numeric code of a client country (as per ISO 3166).

typeId integer

The identifier of a client type.

managerId integer

The identifier of a client manager.

levelId integer

The identifier of a verification level granted to a client.

company string

The name of a client company.

companyFull string

The full name of a client company.

companyRegistration string

The registered company name.

registrationNumber string

The registration number of a client company.

nickname string

The client username.

locale string

The locale identifier (such as en_US).

applicationColor string

The color used to highlight client requests in the Back Office. You can specify the color name, or define its HEX or RGBA value.

email string

The email address used by a client to sign in to the B2Core UI.

tags array

An array of string values specifying the tags assigned to a client.

verificationDisabled integer

If 1, a client is allowed to obtain a higher verification level; otherwise, 0.

internalType integer

The identifier of an internal client type. Possible values:

  • 0 — default

  • 1 — b2b

  • 2 — demo

  • 3 — exchange

  • 4 — agent

status integer

The identifier of a client profile status. Possible values:

  • 1 — active

  • 10 — banned

  • 20 — deleted

  • 0 — inactive

avatar string

The name of an image file used as a profile photo.

riskLevel integer

The identifier of a risk level assigned to a client profile. Possible values:

  • 0 — low

  • 2 — middle

  • 3 — high

PATCH[host]/api/v2/clients/{clientId}

curl --location --request PATCH 'https://host.name/api/v2/clients/1' \
--header 'Authorization: Bearer <token>' \
--header 'accept-language: ja' \
--data-raw '{
  "tfaProvidersForDisable": [
    "sms",
    "google"
  ],
  "givenName": "John",
  "familyName": "Doe",
  "middleName": "James",
  "birthday": "2022-01-01T00:00:00+00:00",
  "maxAccountsDemo": 1,
  "maxAccountsTrade": 3,
  "sex": 1,
  "countryCode": 840,
  "typeId": 1,
  "managerId": 7,
  "levelId": 2,
  "company": "Trading Factory",
  "companyFull": "Trading Factory Inc.",
  "companyRegistration": "Trading Factory Inc.",
  "nickname": "",
  "locale": "en_EN",
  "registrationNumber": "1234567890",
  "applicationColor": "#FFFFFF",
  "email": "john.doe@example.com",
  "tags": [
    "tag1",
    "tag2"
  ],
  "verificationDisabled": 1,
  "internalType": 4,
  "status": 1,
  "avatar": "image.png",
  "riskLevel": 1
}'

Response

A response includes a Client object providing the information about the updated client profile.

Remove a client profile

Use this method to remove a specified client profile.

Request

Header parameters:

  • Authorization: Bearer <token>

Path parameters:

clientID required

The client identifier.

DELETE[host]/api/v2/clients/{clientId}

curl --location --request DELETE 'https://host.name/api/v2/clients/1' \
--header 'Authorization: Bearer <token>' \
--header 'accept-language: ja'

Response

In case of success, no response body is returned.