The CentreSubjectAssociation Resource on the Surpass API can be used to search and filter the associations between centres and subjects in Surpass. New associations can be made and existing associations can be updated or deleted by calling the below methods.
Below we have listed the operations, HTTP verbs and an example URL for the CentreSubjectAssociation resource within the Surpass API.
|Operation||HTTP Verb||Example URL|
|Filter||GET||https://...surpass.com/api/v2/CentreSubjectAssociation?$filter=centre/reference eq ‘JLTC’|
Attributes for the CentreSubjectAssociation
Resource Within the table below we have provided all of the attributes included in the CentreSubjectAssociation resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.
|Attribute Name||Type||Order (GET)||Filter (GET)||Available Operators (GET)||Unique Identifier||Mandatory for Create (POST)||Default|
|id||int||X||X||Numeric OData operators|
- ID is the unique identifier for this resource in the Database.
- Resource reference is the reference allocated to the resource within Surpass.
- ID or reference can be used with this resource
- Primary indicates whether the centre specified as part of the POST request will be set as the primary centre allocated to the subject in Surpass. As a default, content can only be delivered to one centre for a subject. However, you can deliver at more than one centre by sharing the subject.
GET Request and Return
The CentreSubjectAssociation resource can be called directly by browsing to the URL. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the CentreSubjectAssociation resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response. This is detailed in the page understanding the Surpass API.
Example GET request & response (JSON)
Example GET request & response (XML)
POST Request and Return
The POST CentreSubjectAssociation method requires the attributes listed above to be submitted as part of the body of the request. This can be submitted in either JSON or XML formet, the content type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request for both formats can be found below.
Example POST request & response (JSON)
Example POST request & response (XML)
Filtering centre and subject associations on resource objects
The GET CentreSubjectAssociation method allows you to filter on resource objects contained within the CentreSubjectAssociation resource. When filtering on these attributes, you need to additionally specify what attribute you are searching on within that resource, so this is built differently to other attributes contained within the CentreSubjectAssociation resource. below we have provided some examples of how these requests are built.
https://...surpass.com/api/v2/CentreSubjectAssociation?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1'
https://...surpass.com/api/v2/CentreSubjectAssociation?$filter=subject/id eq 21 and centre/id eq 25
Example DELETE request
Successful deletes will return a status of 200.
To successfully call the CentreSubjectAssociation method, the user specified in the header of the request must have the ‘Manage Centres’ and ‘Manage Subjects’ permissions in Surpass.