CentreSubjectAssociation API
In Surpass, you can manage a centre’s associated subjects and centre-level users’ access to these subjects.
The CentreSubjectAssociation API resource is used to list, retrieve, create, update, and delete centre and subject associations.
This article explains what calls can be made to the Surpass API using the CentreSubjectAssociation resource.
Import this API into your Postman Workspace
In This Article
Listing centre and subject associations
Send a request to the endpoint to list centre and subject associations. 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/CentreSubjectAssociation?$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/CentreSubjectAssociation?$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/CentreSubjectAssociation?$filter={filter} {operator} {value} |
Filters results, searching for an exact match. For an exact match: {filter} is one of id, centre/id, centre/reference, subject/id, subject/reference, primary, {operator} is eq (equal to), and {value} is the string, integer or Boolean the filter query looks for an exact match for in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/CentreSubjectAssociation?$orderBy={attribute} |
Determines order of results, where {attribute} is one of id, centre, subject, primary. |
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": 333,
"top": 5,
"skip": 0,
"pageCount": 34,
"nextPageLink": "https://{your Surpass instance}.com:443/api/v2/CentreSubjectAssociation?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"centre": {
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.com/api/v2/Centre/1"
},
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.com/api/v2/Subject/1",
"name": "Subject 1"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/1"
},
{
"id": 2,
"centre": {
"id": 2,
"reference": "Centre2",
"href": "https://{your Surpass instance}.com/api/v2/Centre/2"
},
"subject": {
"id": 2,
"reference": "Subject2",
"href": "https://{your Surpass instance}.com/api/v2/Subject/2",
"name": "Subject 2"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/2"
},
{
"id": 3,
"centre": {
"id": 3,
"reference": "Centre3",
"href": "https://{your Surpass instance}.com/api/v2/Centre/3"
},
"subject": {
"id": 3,
"reference": "Subject3",
"href": "https://{your Surpass instance}.com/api/v2/Subject/3",
"name": "Subject 3"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/3"
},
{
"id": 4,
"centre": {
"id": 4,
"reference": "Centre4",
"href": "https://{your Surpass instance}.com/api/v2/Centre/4"
},
"subject": {
"id": 4,
"reference": "Subject4",
"href": "https://{your Surpass instance}.com/api/v2/Subject/4",
"name": "Subject 4"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/4"
},
{
"id": 5,
"centre": {
"id": 5,
"reference": "Centre5",
"href": "https://{your Surpass instance}.com/api/v2/Centre/5"
},
"subject": {
"id": 5,
"reference": "Subject5",
"href": "https://{your Surpass instance}.com/api/v2/Subject/5",
"name": "Subject 5"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/5"
}
],
"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 centre and subject associations there are in total.
top integer
Details number of centre and subject associations returned in the response.
skip integer
Details how many centre and subject associations were skipped to display those in the response.
pageCount integer
Details how many pages of centre and subject associations there are.
nextPageLink string
The endpoint to call the next page of centre and subject associations. If null, the response is the last page of centre and subject associations.
prevPageLink string
The endpoint to call the previous page of centre and subject associations. If null, the response is the first page of centre and subject associations.
response array
Contains the rest of the response.
id integer
The centre and subject association’s unique identifier.
centre object
Contains the centre the subject is associated with.
centre/id integer
The centre’s unique identifier.
centre/reference string
The centre’s unique reference code.
centre/href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
subject object
Contains the subject the centre is associated with.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
href string
The endpoint to call the centre and subject association’s information, such as /api/v2/CentreSubjectAssociation/{id} where {id} is the centre and subject association’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving centre and subject association information
Send a request to the endpoint to retrieve information for a specific centre and subject association 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/CentreSubjectAssociation/{id} |
Returns information for the specified centre and subject association, where {id} is the centre and subject association’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": 1,
"centre": {
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.com/api/v2/Centre/1"
},
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.com/api/v2/Subject/1",
"name": "Subject 1"
},
"href": "https://{your Surpass instance}.com/api/v2/CentreSubjectAssociation/1",
"primary": true,
"permissions": [
{
"id": 2,
"assignable": true
}
]
}
],
"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 centre and subject associations there are in total. This is null because the information retrieved is for a specific centre and subject association.
top integer
Details number of centre and subject associations returned in the response. This is null because the information retrieved is for a specific centre and subject association.
skip integer
Details how many centre and subject associations were skipped to display those in the response. This is null because the information retrieved is for a specific centre and subject association.
pageCount integer
Details how many pages of centre and subject associations there are. This is null because the information retrieved is for a specific centre and subject association.
nextPageLink string
The endpoint to call the next page of centre and subject associations. This is null because the information retrieved is for a specific centre and subject association.
prevPageLink string
The endpoint to call the previous page of centre and subject associations. This is null because the information retrieved is for a specific centre and subject association.
response array
Contains the rest of the response.
id integer
The centre and subject association’s unique identifier.
centre object
Contains the centre the subject is associated with.
centre/id integer
The centre’s unique identifier.
centre/reference string
The centre’s unique reference code.
centre/href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
subject object
Contains the subject the centre is associated with.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
href string
The endpoint to call the centre and subject association’s information, such as /api/v2/CentreSubjectAssociation/{id} where {id} is the centre and subject association’s unique identifier.
primary boolean
Determines whether the centre is the primary centre associated with the subject. The centre associated with the subject when the subject was created is the primary centre.
permissions array
The level of access centre-level users have to the subject.
permissions/id integer
The unique identifier for the role that centre-level users have for the subject.
permissions/assignable boolean
Determines whether centre-level users can assign the role to other centre-level users for the subject.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a centre and subject association
Send a request to the endpoint to create a centre and subject association.
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. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to create a centre and subject association.
{
"centre": {
"id": "1"
},
"subject": {
"id": "1"
},
"permissions": [
{
"id": 2,
"assignable": true
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
centre object mandatory
Contains the centre the subject is associated with.
centre/id integer
The centre’s unique identifier.
centre/reference string
The centre’s unique reference code.
subject object mandatory
Contains the subject the centre is associated with.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
permissions array mandatory
The level of access centre-level users have to the subject.
permissions/id integer
The unique identifier for the role that centre-level users have for the subject.
permissions/assignable boolean
Determines whether centre-level users can assign the role to other centre-level users for the subject. Defaults to false if omitted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new centre and subject’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/CentreSubjectAssociation/1",
"errors": null,
"serverTimeZone": null
}Updating a centre and subject association
Send a request to the endpoint to update a specific centre and subject association.
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. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
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/CentreSubjectAssociation/{id} |
Update specified centre and subject association, where {id} is the centre and subject association’s unique identifier. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a centre and subject association. Refer to the request body schema for all properties that can be updated.
{
"permissions": [
{
"id": 3,
"assignable": false
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
centre object
Contains the centre the subject is associated with.
centre/id integer
The centre’s unique identifier.
centre/reference string
The centre’s unique reference code.
subject object
Contains the subject the centre is associated with.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
permissions array
The level of access centre-level users have to the subject.
permissions/id integer
The unique identifier for the role that centre-level users have for the subject.
permissions/assignable boolean
Determines whether centre-level users can assign the role to other centre-level users for the subject.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated centre and subject association details.
{
"id": 1,
"reference": " ",
"href": "https://{your Surpass instance}.surpass.com/api/v2/CentreSubjectAssociation/1",
"errors": null,
"serverTimeZone": null
}Deleting a centre and subject association
Send a request to the endpoint to delete a specific centre and subject association. 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/CentreSubjectAssociation/{id} |
Deletes specified centre and subject association, where {id} is the centre and subject association’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the centre has been deleted by returning a null id.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}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. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidReference |
11 |
The unique reference code used in the request is invalid. |
|
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/CentreSubjectAssociation?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
CentreSubjectAssociationNotExists |
54 |
The centre and subject association specified in the request does not exist. |
|
CentreSubjectAssociationAlreadyExists |
55 |
The centre and subject association specified in the request already exists. |
|
CentreSubjectAssociationForMainCentre |
56 |
There is an issue with the centre specified in the request. |
|
CentreSubjectAssociationIsPrimary |
57 |
There is an issue with the primary centre specified in the request. |
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: