Operations with cTID

All API calls in this section concern operations with cTID entities ('users').

All URLs for the API calls described in this section are relative to https://HOST:PORT/cid. The value of HOST:PORT is provided during the onboarding process by Spotware's service assurance team.

Create a cTID

HTTP Method	URL
POST	/ctid/create

Creates a new user entity.

warning

Note that this API call cannot be used for creating new cTIDs as part of our SSO (OAuth) solution. For more information, please refer to our SSO (OAuth) documentation.

Parameters

No parameters.

Request Body

Key	Required?	Data Type	Description
brokerName	No	string	A unique name denoting a specific broker (including White Labels).
email	Yes	string	The email address assigned to the new user.
preferredLanguage	No	string	An Alpha-2 code denoting the preferred language of the new user.

Output

info

Note that there are two possible outputs depending on whether you specify a unique email in the request body (an email that is not used by any of the users registered on your server). If email is unique, the response will include all parameters from the below table. If the specified email is already assigned to an existing user, the output will only include the userId parameter.

Key	Data Type	Description
userId	integer	The unique identifier of the user entity.
nickname	string	The nickname of the user entity. By default, nickname=ctid{userId}.
email	string	The email assigned to the user entity.
preferredLanguage	string	An Alpha-2 code denoting the preferred language of the user entity.
utcCreateTimestamp	integer	The epoch unix timestamp of the creation of the user entity.
status	enum	The status of the new user entity. Possible values: - "CTID_NEW". The default status for any new user. - "CTID_ACTIVE". The status denoting an existing active user who has confirmed their email address in the cTrader ecosystem. Note that only users with "CTID_ACTIVE" as their status receive trading notifications in their email inbox. - "CTID_DELETED". The status denoting a deleted user entity. Note that receiving "CTID_ACTIVE" or "CTID_DELETED" in the response body would constitute unexpected behavior.

For a JSON schema of the output, click here.

Request Example

curl -X POST 'https://HOST:PORT/cid/ctid/create?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"brokerName": "BESTBROKER", "email": "president@bestbroker.com", "preferredLanguage": "EN"}' 

Response Examples

If a Unique `email` Is Specified

{
  "userId": 10333,
  "nickname": "ctid10333",
  "email": "president@bestbroker.com",
  "utcCreateTimestamp": 1679898064783,
  "preferredLanguage": "en",
  "status": "CTID_NEW"
}

If an Existing `email` Is Specified

{
  "userId": 10333
}

Expected Status Code

200

Link an Account to a cTID

HTTP Method	URL
POST	/ctid/link

Links a trader entity to a user entity.

Parameters

No parameters.

Request Body

Key	Required?	Data Type	Description
traderLogin	Yes	integer	The number of a specific trading account. This is functionally the same parameter as login as detailed in API call 4.1 and related calls.
traderPasswordHash	Yes	string	The MD5 of the account password.
userId	Yes	integer	The unique identifier of a user entity.
brokerName	Yes	string	A unique name denoting a specific broker (including White Labels).
environmentName	Yes	string	A unique name of a specific trading environment where the specified traderLogin is registered.
returnAccountDetails	No	boolean	A flag that denotes whether the ctidTraderAccountId key is returned in the response to this API call. Set it to true to ensure that the response to this call is not empty.

Output

Key	Data Type	Description
ctidTraderAccountId	integer	The unique identifier of the linkage between a specific user and one of their trading accounts.

Request Example

curl -X POST 'https://HOST:PORT/cid/ctid/link?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"environmentName": "demo", "brokerName": "BESTBROKER", "traderLogin": 9017800, "traderPasswordHash": "0f94e246908667af85916300c57f74b6", "userId": 10333, "returnAccountDetails": true}' 

Response Example

{
    "ctidTraderAccountId": 8673590
}

Expected Status Code

200

Change Trading Account Details

HTTP Method	URL
POST	/ctid/changeCtidTraderAccount

Changes the White Label (brokerage/jurisdiction) under which a specific trader is registered, or updates a specific trader's display name, which is shown in the UI in place of login number.

Parameters

No parameters.

Request Body

Key	Required?	Data Type	Description
brokerName	No	string	A unique name denoting the new broker to which the trader should be attributed.
brokerAccountDisplayName	No	string	Text to show in place of login number in UI.
traderLogin	Yes	integer	The number of the trading account that you would like to transfer to a different broker. This is functionally the same parameter as login as detailed in API call 4.1 and related calls.
environmentName	Yes	string	A unique name of a specific trading environment.

Output

No output.

Request Example

curl -X POST 'https://HOST:PORT/cid/ctid/changeCtidTraderAccount?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"brokerAccountDisplayName": "EXAMPLE", "environmentName": "live", "traderLogin": 8211616}'

Response Example

This API call does not produce an output.

Expected Status Code

200

Send Push Notification to Users

HTTP Method	URL
POST	/push/send

Sends push message to users.

Parameters

No parameters.

Request Body

Key	Required?	Data Type	Description
users	No	array	List of user IDs. If specified, only the users with the specified IDs will receive the push notification.
allGroups	Yes	boolean	If true, the value of the group parameter will be ignored, and users will receive the push notification regardless of the groups to which their accounts belong.
groups	No	array	List of group IDs. If specified, only users with accounts belonging to the specified groups will receive the push notification.
allPreferredLanguages	Yes	boolean	If true, the value of the preferredLanguage parameter will be ignored, and users will receive the push notification regardless of their preferred language in the cTrader application.
preferredLanguages	No	array	List of languages (2 characters each). Only users whose preferred cTrader application language matches the value of this parameter will receive the push notification.
message	Yes	JSON object	The push message that will be sent to users.
message.title	Yes	string	The title of the message.
message.body	Yes	string	The body of the message.
message.imageURL	No	string	The URL for the image used in the push message.
message.deepLinkAction	No	string	The action performed when a user taps on the message. Possible values include orders, positions, transactions and symbols/{SymbolName}/info, which open different screens. Interacting with the push notification opens the corresponding screen. If unspecified, the cTrader application will be opened on the main screen.
brokerName	Yes	string	Only users with accounts registered with this brokerName will receive the push notification.

Output

Key	Data Type	Description
usersAmount	integer	Number of users that will get the push message.
messagesAmount	integer	Number of messages that will be sent.

Request Example

curl -X POST 'https://HOST:PORT/cid/push/send?token=7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d7' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"users": [43581], "allGroups": true, "allPreferredLanguages": true, "brokerName": "BESTBROKER", "message": {"title": "test", "body": "test"} }'

Response Example

{
  "usersAmount": 1,
  "messagesAmount": 51
}

Expected Status Code

200

Get cTID Email of Trader

HTTP Method	URL
GET	/ctid/getemail/{traderLogin}

Gets the email associated with the cTID of a trader.

Parameters

Parameter	Parameter Type	Required?	Data Type	Description
traderLogin	path	Yes	integer	The number of a specific trading account. This is functionally the same parameter as login as detailed in API call 4.1 and related calls.
environmentName	query	No	string	A unique name of a specific trading environment where the specified traderLogin is registered.

Request Body

No request body.

Output

Key	Data Type	Description
ctidEmail	string	The cTID email of a trader.

Request Example

curl -X GET 'https://HOST:PORT/cid/ctid/getemail/9017800?token=7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d7&environmentName=demo'

Response Example

{
  "ctidEmail": "letstrade@email.com"
}

Expected Status Code

200

Get User ID by Email

HTTP Method	URL
GET	/ctid/getUserId

Gets the unique identifier of a user entity through the email of the user.

Parameters

Parameter	Parameter Type	Required?	Data Type	Description
email	path	Yes	string	The email of the user

Request Body

No request body

Output

Key	Data Type	Description
userId	integer	The unique identifier of a user entity.

Request Example

curl -X GET 'https://HOST:PORT/cid/ctid/getUserId?token=7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d7&email=letstrade@email.com'

Response Example

{
    "userId": 421983
}

Expected Status Code

200

Get List of User Accounts

HTTP Method	URL
POST	/ctidTraderAccounts

Gets a list of user accounts and cTID details.

Headers

Header	Description	Required?
Authorisation Bearer	Authorisation header containing the authentication token of the manager. E.g. 'Authorization: 7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d8'.	Yes

Parameters

No parameters.

Request body

Key	Required?	Data Type	Description
limit	No	integer	The maximum number of records to be returned.
skip	No	integer	The number of records to be skipped after sorting by utcCreateTimestamp.
from	No	integer	The epoch unix timestamp at which filtering starts. Only cTIDs registered at or after this timestamp are returned.
to	No	integer	The epoch unix timestamp at which filtering ends. Only cTIDs registered before this timestamp are returned.
traderIds	No	array	An array of trader account IDs for filtering.
traderLogins	No	array	An array of trader logins for filtering.
userId	No	integer	The specific unique ID of a specific user for filtering.
environmentName	Yes	string	The unique name of a specific trading environment where the cTIDs are registered.

Output

Key	Data Type	Description
accounts	array	The list of user accounts already linked to cTIDs as JSON objects.
ctidTraderAccount.userId	integer	The unique identifier of a user entity.
ctidTraderAccount.ctidTraderAccountId	integer	The unique identifier of the link between a specific user and one of their trading accounts.
ctidTraderAccount.login	integer	The number of a specific trading account.
ctidTraderAccount.subAccountOf	integer	The trader login of the main account for the subaccount.
ctidTraderAccount.moneyDigits	integer	The number that determines how finance-related values are defined for the account. E.g., if moneyDigits=2 and balance=1234512, the account balance is 12345.12 in the account deposit currency. Additional details are given in Section 3.
ctidTraderAccount.brokerName	string	The unique name denoting a specific broker (including White Labels).
ctidTraderAccount.depositCurrency	string	The name of the currency that the account uses for making deposits and withdrawals.
ctidTraderAccount.utcCreateTimestamp	integer	The epoch unix timestamp of the creation of the user entity.
ctidTraderAccount.sharedWithUserId	integer	The ID of the user who was granted access to this account by the owner.
ctidTraderAccount.environmentName	string	The unique name of the specific trading environment where the cTIDs are registered.
ctidTraderAccount.brokerAccountDisplayName	string	Text to show in place of login number in UI.
unlinkedTraderIds	array	An array of unlinked trader IDs.
unlinkedTraderLogins	array	An array of unlinked trader logins.

Request Example

curl -X POST 'https://HOST:PORT/ctidTraderAccounts' -H 'Authorization: 7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d8' -H 'Content-Type: application/json' -H 'Accept: application/json'  -d '{"from": 1669078973998, "to": 1790000000000, "traderIds": [88903, 96957, 99999], "userId": 845, "environmentName": "live", "limit": 100, "skip": 0}' 

Response Example

{
  "accounts": [
    {
      "userId": 845,
      "ctidTraderAccountId": 78276,
      "login": 8044752,
      "subAccountOf": 79239,
      "moneyDigits": 0,
      "brokerName": "BESTBROKER",
      "depositCurrency": "JPY",
      "utcCreateTimestamp": 1719994629851,
      "sharedWithUserId": null,
      "environmentName": "live",
      "brokerAccountDisplayName": "EXAMPLE"
    },
    {
      "userId": 845,
      "ctidTraderAccountId": 65191,
      "login": 8036691,
      "subAccountOf": null,
      "moneyDigits": 2,
      "brokerName": "BESTBROKER",
      "depositCurrency": "AUD",
      "utcCreateTimestamp": 1689078973998,
      "sharedWithUserId": null,
      "environmentName": "live",
      "brokerAccountDisplayName": null
    }
  ],
  "unlinkedTraderIds": [],
  "unlinkedTraderLogins": []
}

Expected Status Code

200