Functions of API Calls
Request format
When interacting with Deriv’s WebSocket API, all requests must be sent as JSON in text frames, with one request per frame.
To help you manage the flow of requests and responses, each API call follows a standardized structure. This structure aids in caching, validation, and synchronizing requests and responses, making your WebSocket connection smoother and more efficient.
API call method name
Every request must include a method name
field, which serves as a unique identifier. Typically, this is set to 1
, but it can sometimes be a string.
The
method name
is always required, as it defines the specific data you’ll receive from the WebSocket server.
Required fields
Each request contains required fields and may also have optional fields. For example, a Residence List
call returns a list of countries and their two-letter codes, suitable for populating an account opening form.
Example request data for residence list:
{
"residence_list": 1, // Method Name
"passthrough": {}, // Optional
"req_id": 2 // Optional
}
The residence_list
field is the method name and is mandatory. Other fields like passthrough
and req_id
are optional and depend on your specific needs.
Optional fields
API calls often include optional fields that you can choose to use or ignore:
passthrough
: This field returns any data you provide within the response object. It’s useful for maintaining state across requests and responses.req_id
: This field allows you to tag requests, making it easier to map them to responses.
For more details on optional fields for each API call, visit the API Explorer.
Response data
Responses from the API will include a field named after the method name
you used in your request. This field contains the actual data.
Example response for residence list:
{
"echo_req": {
"req_id": 1,
"residence_list": 1
},
"msg_type": "residence_list",
"req_id": 1,
"residence_list": [
{
"identity": {
"services": {
"idv": {
"documents_supported": {},
"has_visual_sample": 0,
"is_country_supported": 0
},
"onfido": {
"documents_supported": {
"driving_licence": {
"display_name": "Driving Licence"
}
},
"is_country_supported": 0
}
}
},
"phone_idd": "35818",
"text": "Aland Islands",
"value": "ax"
},
{
"identity": {
"services": {
"idv": {
"documents_supported": {},
"has_visual_sample": 0,
"is_country_supported": 0
},
"onfido": {
"documents_supported": {
"driving_licence": {
"display_name": "Driving Licence"
},
"national_identity_card": {
"display_name": "National Identity Card"
},
"passport": {
"display_name": "Passport"
}
},
"is_country_supported": 1
}
}
},
"phone_idd": "355",
"text": "Albania",
"tin_format": [
"^[A-Ta-t0-9]\\d{8}[A-Wa-w]$"
],
"value": "al"
}
]
}
The residence_list
field in this response contains the requested data. For the complete response, check the API Explorer.
Response fields
echo_req
: This field returns the exact request data that was sent to the server, useful for verification and debugging.msg_type
: Identifies the type of message received from the server, which is helpful for managing responses in your WebSocketonmessage
event handler.req_id
: An optional field used for validation, synchronization, or caching.
JavaScript example for handling responses:
socket.onmessage = (event) => {
const receivedMessage = JSON.parse(event.data);
switch (receivedMessage.msg_type) {
case "residence_list":
console.log("The residence list is:", receivedMessage.residence_list);
break;
case "other_request_identifier":
console.log("The response:", receivedMessage.some_other_request_identifier);
break;
default:
console.log("Received message:", receivedMessage);
break;
}
};
The
msg_type
field is always present in the response data, helping you manage the incoming messages efficiently.
Updated about 1 month ago