ASP.NET Web API Help Page

Introduction

This API is for connection of a website to user profiles in the CRM system

Media Types

The API supports HAL (Hypertext Application Langugage). To receive the full benefit of this, a client system shold request application/hal+json

Authentication

Most end points in the API require authentication using a token acquired from Windows Azure Active Directory.
See Sample PHP Code
Client Id and Client Secret keys are issued by SSAT Information Services

API versioning

The canonical endpoints for all operations are at /api/{resource}/{further parameters}. Clients should indicate which version of the API they require by setting a "X-Api-Version" header to the integer API version

Requests to the canonical address without a "X-Api-Version" header will be served by the default API version

Some resources (as shown below) may also be available with API versioning in the URL (e.g. /api/v1/{resource}/{further parameters}). This should be considered as an aid to testing and may not always be supported - the preferred versioning approach is to use the "X-Api-Version" request header.

Current API version	1
Default API version	1
Accepted API version(s)	1

Users

Actions relating to user records in CRM

API	Description
GET api/users?page={page}&pageSize={pageSize}	GET api/users Requires authentication. Get a paged list of all users If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users/{id}	Requires authentication. Get an individual user by GUID. If successful returns "200 OK", with the body of the response containing a representation of the user. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users?xrmContactId={xrmContactId}	Get user details by XrmContactId - used if we do not have user Id
PUT api/users/{id}	PUT api/users/5d1b0b57-7535-4880-9aa5-1b71ffd76fff Request body should be user fields for the fields that are to be updated Currently only supports changes to FirstName, Lastname, Email, JobTitle, JobRole and Telephone All these values are optional, can be left out of request if not to be updated. If successful returns 200 OK and the new User record in the body For CRM faults returns 504 Bad Gateway If user body contains Login (which are invariant through this process) returns 400 Bad Request If user body contains Id it must be the same as the Id in the URL else returns 400 Bad Request If the user or jobRole are not known values then returns a 404 Not Found
DELETE api/users/{id}	Deletes the user record in CRM associated with the Id. Does not delete CRM contact.
POST api/users/validation	These are the NEW semantics for this endpoint. Used to pre-validate a partial user record (Email, Firstname, Lastname) POST a user record in the body of a request to /api/users/validation. If the user is valid and a record already exists in CRM returns 200 OK and the full user record in the body. If the user is associated with an organisaiton in CRM, the organisaitonId and organisaiton memebrship number are returned. If the user is valid but does not yet exist in CRM, record(s) are created in CRM and the endpoint returns 201 Created, with the user record in the body. If there is an organisation membership number attached, then that is checked against CRM. If not found, then a 400 is returned. If the organisaiton memebrship number is recognised but the user is not currently associated with that organisaiton in CRM, then we move the user to that organisation. For syntax errors returns 400 Bad Request and a message that explains the error in the response body CRM errors will return 502 Bad gateway, any other errors 500 Internal Server Error.
POST api/users/{id}/registration	POST api/users/{id:guid}/registration Records in CRM that the given user has successfully registered on the website If successful returns 200 OK with the updated user in the body If backend user record exists but is not in a state from which there is a valid "Registered" transition, then returns conflict with a helpful error message. If the user does not exist in the backend (so cannot be registered) returns 404 Not Found. Other CRM errors give 502 bad gateway, any other errors 500 Server Error
POST api/users/{id}/confirmation	POST api/users/{id:guid}/confirmation Records in CRM that the given user has successfully been confirmed as a member of said organisation on the website If successful returns 202 Accepted with the updated user in the body If backend user record exists but is not in a state from which there is a valid "Confirmation" transition, then returns conflict with a helpful error message. the backend (so cannot be confirmed) returns 404 Not Found. If the user's organsiation does not exist in the backend (so cannot be confirmed) returns 402 Bad Request. Other CRM errors give 502 bad gateway, any other errors 500 Server Error
POST api/users/{id}/disassociation	POST api/users/{id:guid}/disassociation Records in CRM that the given user has successfully been disassociated as a member of any organisation on the website If successful returns 200 OK with the updated user in the body If backend user record exists but is not in a state from which there is a valid "disassociation" transition, then returns conflict with a helpful error message. the backend (so cannot be disassociated) returns 404 Not Found. Other CRM errors give 502 bad gateway, any other errors 500 Server Error

Roles

Actions which return information about web roles defined in the back-end system Currently none of these are implemented

API	Description
GET api/roles/{roleset}	GET api/roles/{roleset:int?} Requires authentication. Get a list of all roles defined in the backend system for the given roleset. If roleset is not defined, defaults to 0
GET api/roles/{id}	Requires authentication. Get details of one role from the backend system
GET api/users/{id}/roles	Requires authentication. Get list of all roles that a given user has
PUT api/users/{id}/promotion	Requires authentication. promote the user in the request to "superuser" If successful returns "200 OK", with the body of the response containing a representation of the the user's responsibilities. If user not found, returns "404 Not Found" If user already assigned to superuser webrole returns 409 Conflict, and the reason phrase gives more details. If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/users/{id}/demotion	Requires authentication. demote the user in the request from "superuser" If successful returns "200 OK", with the body of the response containing a representation of the the user's responsibilities. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

Venues

Retrieve details of event venues

API	Description
GET api/venues/{id}	GET /api/venues/{id:guid} If successful returns venue details and 200 OK Sets Etag header but as yet DOES NOT SUPPORT requests with "If-None-Match" header If Id is null or Guid.Empty returns 400 Bad Request If venue not found in active venue list in CRM returns 404 Not Found For errors contacting CRM returns 502 Bad Gateway All other errors 500
GET api/venues?page={page}&pagesize={pagesize}&updatedsince={updatedsince}	Returns list of venues. Returns 200 OK and list of venues. If a badly formed updatedsince parameter is sent, service treats as null so returns all venues. If no venues, returns 404 Not Found. For CRM error returns 502 Bad Gateway. For otehr errors 500. optional query string parameters: page, pagesize, updatedsince
GET api/events/{id}/venue	GET /api/events/{id:guid}/venue Get the venue details for an event, by event Id If successful returns venue details and 200 OK Sets Etag header but as yet DOES NOT SUPPORT requests with "If-None-Match" header If Id is null or Guid.Empty returns 400 Bad Request If venue not found in active venue list in CRM returns 404 Not Found For errors contacting CRM returns 502 Bad Gateway All other errors 500

Skills

Actions relating to user records in CRM

API	Description
GET api/skills	Requires authentication. Get all skills, no paging support as total number of skills quite small If successful returns "200 OK", with the body of the response containing a representation of the set of skills. If not found, returns "404 Not Found" - there should always be some skills If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/skills/{id}	Requires authentication. Get an individual skill by GUID. If successful returns "200 OK", with the body of the response containing a representation of the skill. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users/{id}/skills	Requires authentication. Returns all skills for a given user If successful returns "200 OK", with the body of the response containing a representation of the the skills. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
POST api/users/{id}/skills	Requires authentication. Updates the user with the set of skills contained in the request body. To clear all skills, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's skills. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/users/{id}/skills	Requires authentication. Updates the user with the set of skills contained in the request body. To clear all skills, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's skills. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users/{id}/skillswanted	Requires authentication. Returns all skills wanted for a given user If successful returns "200 OK", with the body of the response containing a representation of the the skills. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
POST api/users/{id}/skillswanted	Requires authentication. Updates the user "skills wanted" with the set of skills contained in the request body. To clear all skills wanted, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's skills. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/users/{id}/skillswanted	Requires authentication. Updates the user "skills wanted" with the set of skills contained in the request body. To clear all skills wanted, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's skills. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

Responsibility

Actions relating to user records in CRM

API	Description
GET api/responsibilities	Requires authentication. Get all responsibilities, no paging support as total number of responsibilities quite small If successful returns "200 OK", with the body of the response containing a representation of the set of responsibilities. If not found, returns "404 Not Found" - there should always be some responsibilities If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/responsibilities/{id}	Requires authentication. Get an individual responsibility by GUID. If successful returns "200 OK", with the body of the response containing a representation of the responsibility. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users/{id}/responsibilities	Requires authentication. Returns all responsibilities for a given user If successful returns "200 OK", with the body of the response containing a representation of the the responsibilities. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/users/{id}/responsibilities	Requires authentication. Updates the user with the set of responsibilities contained in the request body. Any responsibilities not in the request but already associated with the user in CRM will be removed. To clear all responsibilities on the user, post an empty list. If successful returns "200 OK", with the body of the response containing a representation of the the user's responsibilities. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

Authtest

Simple authenticated test URLs for basic client testing

API	Description
GET api/authtest	Requires authentication. Get an array of strings.
GET api/authtest/{id}	Requires authentication. Get a single string

Invitations

Endpoint for checking status of an invitation code

API	Description
GET api/invitations/{id}	Check if invitation code is valid, by GET to /api/invitations/{invitationcode}. If code is valid, returns 200 OK and an extended resource containing invitation Id and associated user record. If code does not exist, returns 404 Not Found. If code exists but is not valid, returns 409 Conflict, and the reason phrase gives more details

Subjects

Actions relating to user records in CRM

API	Description
GET api/subjects	Requires authentication. Get all subjects, no paging support as total number of subjects quite small If successful returns "200 OK", with the body of the response containing a representation of the set of subjects. If not found, returns "404 Not Found" - there should always be some subjects If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/subjects/{id}	Requires authentication. Get an individual subject by GUID. If successful returns "200 OK", with the body of the response containing a representation of the subject. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/users/{id}/subjects	Requires authentication. Returns all subjects for a given user If successful returns "200 OK", with the body of the response containing a representation of the the subjects. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
POST api/users/{id}/subjects	Requires authentication. Updates the user with the set of subjects contained in the request body. To clear all subjects, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's subjects. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/users/{id}/subjects	Requires authentication. Updates the user with the set of subjects contained in the request body. To clear all subjects, send an empty list If successful returns "200 OK", with the body of the response containing a representation of the the user's subjects. If user not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

Products

API	Description
GET api/products?page={page}&pagesize={pagesize}&updatedsince={updatedsince}	Requires authentication. Get products list If successful returns "200 OK", with the body of the response containing a representation of the products list If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/products/{id}	Requires authentication. Get an individual Product by GUID. If successful returns "200 OK", with the body of the response containing a representation of the Product. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

JobRoles

Actions relating to user records in CRM

API	Description
GET api/jobroles	Requires authentication. Get all jobroles, no paging support as total number of jobroles quite small If successful returns "200 OK", with the body of the response containing a representation of the set of jobroles. If not found, returns "404 Not Found" - there should always be some jobroles If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/jobroles/{id}	Requires authentication. Get an individual jobrole by GUID. If successful returns "200 OK", with the body of the response containing a representation of the jobrole. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

API

Description

GET api/jobroles

Requires authentication. Get all jobroles, no paging support as total number of jobroles quite small If successful returns "200 OK", with the body of the response containing a representation of the set of jobroles. If not found, returns "404 Not Found" - there should always be some jobroles If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

GET api/jobroles/{id}

Requires authentication. Get an individual jobrole by GUID. If successful returns "200 OK", with the body of the response containing a representation of the jobrole. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

Test

Simple unauthenticated test URLs for basic client testing

API	Description
GET api/test	Get an array of strings
GET api/test/{id}	Get a single string

Orgs

API	Description
GET api/orgs/{id}	Requires authentication. Get an individual org by GUID. If successful returns "200 OK", with the body of the response containing a representation of the organisation. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
GET api/orgs/{id}/users	Requires authentication. Get users associated with specified org. The org is idenified using it's GUID id If successful returns "200 OK", with the body of the response containing a representation of the organisation's users. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
PUT api/orgs/{id}	PUT api/orgs/5d1b0b57-7535-4880-9aa5-1b71ffd76fff Request body should be org fields for the fields that are to be updated Fields that can be updated and included in request body are : Address1 Address2 Address3 AddressCity AddressCountry AddressCounty AddressPostCode AddressState FinanceEmail FinanceTelephone Name OfficeEmail OfficeTelephone If successful returns 200 OK and the new User record in the body For CRM faults returns 504 Bad Gateway If org body contains Id or OrgMemberNumber (which are invariant through this process) returns 400 Bad Request

Events

Retrieve details of Events

API	Description
GET api/events/{id}	GET /api/events/{id:guid} If successful returns event details and 200 OK Sets Etag header but as yet DOES NOT SUPPORT requests with "If-None-Match" header If Id is null or Guid.Empty returns 400 Bad Request If event not found in active event list in CRM with "show on web" set, returns 404 Not Found For errors contacting CRM returns 502 Bad Gateway All other errors 500
GET api/events?page={page}&pagesize={pagesize}&updatedsince={updatedsince}	Returns list of events. Returns 200 OK and list of events. If a badly formed updatedsince parameter is sent, service treats as null so returns all events. If no events, returns 404 Not Found. For CRM error returns 502 Bad Gateway. For otehr errors 500. optional query string parameters: page, pagesize, updatedsince

NewsLetters

API	Description
GET api/users/{id}/newsletters	Requires authentication. Get newsletters associated with specified user. The user is identified using its GUID id If successful returns "200 OK", with the body of the response containing a representation of the newsletters to which the user is entitled If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"
POST api/users/{id}/newsletters	Requires authentication. Updates newsletter subscriptions for specified user. The user is identitfied by GUID id If successful returns "200 OK", with the body of the response containing a representation of the organisation's users. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

API

Description

GET api/users/{id}/newsletters

Requires authentication. Get newsletters associated with specified user. The user is identified using its GUID id If successful returns "200 OK", with the body of the response containing a representation of the newsletters to which the user is entitled If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"

POST api/users/{id}/newsletters

Requires authentication. Updates newsletter subscriptions for specified user. The user is identitfied by GUID id If successful returns "200 OK", with the body of the response containing a representation of the organisation's users. If not found, returns "404 Not Found" If CRM operations fail for an un-recoverable reason, the service returns "502 Bad Gateway" Any other server-side errors return "500 Internal Server Error"