Country API
The Surpass Country API lets you retrieve the unique identifier for each country. These identifiers can be used when assigning a country to a resource, for example, when creating centres using the Centre API. For more information on the Centre resource, read Centre API.
The Country API resource is used to list and retrieve countries.
This article explains what calls can be made to the Surpass API using the Country resource.
Import this API into your Postman Workspace
In This Article
Listing countries
Send a request to the endpoint to retrieve a list of countries. Refer to the available parameters to influence the response. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/Country?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/Country?$skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
|
filter |
query OPTIONAL |
/api/v2/Country?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is id, {operator} is eq (equal to), and {value} is the integer the filter query looks for an exact match for in the request. For a greater than query: {filter} is id, {operator} is ge (greater than), and {value} is the integer the filter looks for more than in the request. For a less than query: {filter} is id, {operator} is le (less than), and {value} is the integer the filter looks for less than in the request. For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is name; and {value} is the string the filter query looks for the data to contain in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/Country?$orderBy={attribute} |
Determines order of results, where {attribute} is name. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 615,
"top": 10,
"skip": 0,
"pageCount": 62,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/Country?$skip=10",
"prevPageLink": null,
"response": [
{}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}
{
"count": 469,
"top": 10,
"skip": 0,
"pageCount": 47,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/Country?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 0,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/0",
"name": "England"
},
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/1",
"name": "Northern Ireland"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/2",
"name": "Scotland"
},
{
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/3",
"name": "Wales"
},
{
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/4",
"name": "Canada"
},
{
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/5",
"name": "United States"
},
{
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/6",
"name": "Afghanistan"
},
{
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/7",
"name": "Albania"
},
{
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/8",
"name": "Algeria"
},
{
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/9",
"name": "American Samoa"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many countries there are in total.
top integer
Details number of countries returned in the response.
skip integer
Details how many countries were skipped to display those in the response.
pageCount integer
Details how many pages of countries there are.
nextPageLink string
The endpoint to call the next page of countries. If null, the response is the last page of countries.
prevPageLink string
The endpoint to call the previous page of countries. If null, the response is the first page of countries.
response array
Contains the rest of the response.
id integer
The country’s unique identifier.
href string
The endpoint to call the country’s information, such as /api/v2/Country/{id} where {id} is the country’s unique identifier.
name string
The country’s name.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving country information
Send a request to the endpoint to retrieve information for a specific country using its ID. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path MANDATORY |
/api/v2/Country/{id} |
Returns information for the specified country, where {id} is the country’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 0,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/0",
"name": "England",
"counties": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/1",
"name": "Greater London"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/2",
"name": "Greater Manchester"
},
{
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/3",
"name": "Merseyside"
},
{
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/4",
"name": "South Yorkshire"
},
{
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/5",
"name": "Tyne and Wear"
},
{
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/6",
"name": "West Midlands"
},
{
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/7",
"name": "West Yorkshire"
},
{
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/8",
"name": "Bedfordshire"
},
{
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/9",
"name": "Buckinghamshire"
},
{
"id": 10,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/10",
"name": "Cambridgeshire"
}
]
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every proeprty that can be returned for this endpoint.
count integer
Details how many countries there are in total. This is null because the information retrieved is for a specific country.
top integer
Details number of countries returned in the response. This is null because the information retrieved is for a specific country.
skip integer
Details how many countries were skipped to display those in the response. This is null because the information retrieved is for a specific country.
pageCount integer
Details how many pages of countries there are. This is null because the information retrieved is for a specific country.
nextPageLink string
The endpoint to call the next page of countries. If null, the response is the last page This is null because the information retrieved is for a specific country.
prevPageLink string
The endpoint to call the previous page of countries. This is null because the information retrieved is for a specific country.
response array
Contains the rest of the response.
id integer
The country’s unique identifier.
href string
The endpoint to call the country’s information, such as /api/v2/Country/{id} where {id} is the country’s unique identifier.
name string
The country’s name.
counties array
All of the counties within the specified country.
counties/id integer
The county’s unique identifier.
counties/href string
The endpoint to call the county’s information, such as /api/v2/County/{id} where {id} is the county’s unique identifier.
counties/name string
The county’s name.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/Country?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: