API release notes 3.1.1

Note: For the following new SSRS endpoints it is important not to send a Staff ID in your request. Your Staff ID will be provided through your Apigee account. This Staff ID must have the necessary permissions to access reports in the IFM system. If you manually add a Staff ID Apigee will overwrite the Staff ID header.

SSRS Reports Endpoints

New Endpoint: /ssrsreports (GET)

Returns a list of all reports. Retrieves a list of all available SSRS (SQL Server Reporting Services) reports that the authenticated staff member can access. Use this endpoint to discover which reports are available for further actions such as running or parameterizing reports.

HTTP Method: GET /ssrsreports

Required Headers

None.

Query Parameters

None. This endpoint does not accept any query parameters.

Request Body

None.

Expected Response

  • Status: 200 OK

  • Body: An array of report objects. Each object represents a report available to the staff member. If no reports are available, an empty array ([]) is returned.

Example Query

{{BASE_URL}}ssrsreports

Example Response

[
			{
			"reportId": "123",
			"name": "Monthly Sales Report",
			"description": "Shows sales data for the selected month.",
			"createdDate": "2024-01-15T10:00:00Z"
			},
			{
			"reportId": "124",
			"name": "Inventory Summary",
			"description": "Lists current inventory levels by category.",
			"createdDate": "2024-02-01T08:30:00Z"
			}
		]

The response array may be empty if no reports are available for the given staff member.

New Endpoint: /ssrsreports (POST)

This request generates a SQL Server Reporting Services (SSRS) report by submitting a POST request to the endpoint. Use this endpoint to generate and retrieve a report from the SSRS server. The report is generated based on the specified report file name, input parameters, and desired output format.

HTTP Method: POST /ssrsreports

Required Headers

Accept (optional): Specify the desired response content type (e.g., text/csv, application/pdf). If omitted, the default format is used based on the outputFormat in the body.

Request Body Structure (JSON)

The body must be sent as raw JSON with the following structure:

{
			"reportFileName": "<string>",
			"parameters": [
			{ "key": "<parameterName>", "value": "<parameterValue>" },
			...
			],
			"outputFormat": "<string>"
		}

Fields

  • reportFileName (string, required): The name of the SSRS report file to generate. Example values: SR2_ARAging, SR2_StaffDetails.

  • parameters (array of objects, required): Each object must have:

    • key (string): The name of the report parameter (e.g., LastDate).

    • value (string): The value for the parameter (e.g., 01/01/2020).

  • outputFormat (string, required): The desired output format for the report. Values include: PDF, CSV

Example Request Body

{
			"reportFileName": "SR2_ARAging",
			"parameters": [
			{
			"key": "LastDate",
			"value": "01/01/2020"
			}
			],
			"outputFormat": "PDF"
		}

Response

  • The response will contain the generated report in the format specified by outputFormat.

  • The Content-Type of the response will match the report format (e.g., application/pdf, text/csv).

  • On success, the response body contains the binary data of the report file.

  • On error, the response will include an error message in the body.

Status Codes

  • 200 OK: Report generated successfully.

  • 400 Bad Request: Missing or invalid parameters.

  • 401 Unauthorized or 403 Forbidden: Invalid or missing authentication/authorization.

  • 500 Internal Server Error: Server-side error during report generation.

Note: Ensure that all required parameters for the selected report are provided in the parameters array. If you expect a specific file type, set the Accept header accordingly. This request is typically used by staff or automated systems to generate business reports for download or further processing. Make sure to validate the report parameters and output format before sending the request.

New Endpoint: /ssrsreports/{ReportLayout}/parameters

This GET request retrieves a list of all report parameters for a specified SSRS report layout. It is used to dynamically obtain the required and optional parameters needed to generate or customize the report.

HTTP Method: GET /ssrsreports/{ReportLayout}/parameters

Query Parameters

  • ReportLayout: The identifier of the report layout for which the parameters are requested. This value cannot be null or empty.

Response

  • Status: 200 OK

  • Body: The response is a JSON array. Each element in the array is an object representing a report parameter with the following fields:

    • name (string): The parameter's name.

    • type (integer): The data type of the parameter (e.g., 1 for date, 3 for number, 4 for string).

    • prompt (string): The label or prompt shown to the user.

    • nullable (boolean): Indicates if the parameter can be null.

    • allowBlank (boolean): Indicates if the parameter can be blank.

    • multiValue (boolean): Indicates if the parameter accepts multiple values.

    • queryParameter (boolean): Indicates if the parameter is expected as a query parameter.

    • validValues (array or null): List of valid values (if applicable), each with label and value.

    • defaultValues (array or null): List of default values (if applicable).

    • promptUser (boolean): Indicates if the user should be prompted for this parameter.

    • state (integer): The state of the parameter (e.g., enabled/disabled).

    • errorMessage (string or null): Any error message related to the parameter.

Use this endpoint to programmatically discover which parameters are required a given report before attempting to generate or preview the report.

Example Query String

ssrsreports/SR2_ARAging

Example Response for SR2_ARAging Report

[
			{
			"name": "Server",
			"type": 4,
			"typeSpecified": true,
			"nullable": false,
			"nullableSpecified": true,
			"allowBlank": false,
			"allowBlankSpecified": true,
			"multiValue": false,
			"multiValueSpecified": true,
			"queryParameter": true,
			"queryParameterSpecified": true,
			"prompt": "Server",
			"promptUser": true,
			"promptUserSpecified": true,
			"dependencies": null,
			"validValuesQueryBased": false,
			"validValuesQueryBasedSpecified": true,
			"validValues": null,
			"defaultValuesQueryBased": false,
			"defaultValuesQueryBasedSpecified": true,
			"defaultValues": null,
			"state": 1,
			"stateSpecified": true,
			"errorMessage": null
			},
			{
			"name": "LastDate",
			"type": 1,
			"typeSpecified": true,
			"nullable": false,
			"nullableSpecified": true,
			"allowBlank": false,
			"allowBlankSpecified": true,
			"multiValue": false,
			"multiValueSpecified": true,
			"queryParameter": true,
			"queryParameterSpecified": true,
			"prompt": "Report Date",
			"promptUser": true,
			"promptUserSpecified": true,
			"dependencies": null,
			"validValuesQueryBased": false,
			"validValuesQueryBasedSpecified": true,
			"validValues": null,
			"defaultValuesQueryBased": false,
			"defaultValuesQueryBasedSpecified": true,
			"defaultValues": null,
			"state": 1,
			"stateSpecified": true,
			"errorMessage": null
			}
		]

OData Endpoints

The following new OData endpoints support standard OData query options (e.g., $top, $skip, $filter, $orderby) for flexible data retrieval.

New Endpoint: /odata/clients

Retrieves a list of all clients from the system.

HTTP Method: GET /odata/clients

Request Parameters

No query parameters are required for this endpoint. OData query options (e.g., $top, $skip, $filter) are supported.

Example Queries

  • To retrieve a list of all clients:

    {{BASE_URL}}odata/clients?

  • To retrieve a list of clients filtered where clientid = 10:

    {{BASE_URL}}odata/clients?$filter=clientid eq 10

  • Example with order by & pagination:

    {{BASE_URL}}odata/clients?$orderby=ClientID asc&$top=10&$skip=400

Response Structure

The response is a JSON array, where each element represents a client object.

Each client object contains the following required fields:

  • clientID (string or number): Unique identifier for the client.

  • firstName (string): Client's first name.

  • email (string): Client's email address.

  • telephone (string): Client's telephone number.

  • suspended (boolean): Indicates if the client is suspended. Must be a boolean value.

  • vatRegistered (boolean): Indicates if the client is VAT registered. Must be a boolean value.

Example Response

Query odata/clients?$filter=clientid eq 10

[
			{
			"clientID": 10,
			"firstName": "",
			"searchName": "Widman, Jeffrey P Esq",
			"clientRef": "10",
			"addressDetail": "19205 S Hill St",
			"city": "Davenport",
			"county": "Scott",
			"country": "USA",
			"postCode": "52806",
			"telephone": "563-318-1571",
			"email": "meri_baldon@baldon.com",
			"suspended": false,
			"vatRegistered": null
			}
		]

Note: The response array will always contain at least one client object if clients exist. The suspended and vatRegistered fields are strictly validated to be boolean values (true or false). A successful response returns HTTP status code 200.

New Endpoint: /odata/staff

Retrieves a list of all staff from the system.

HTTP Method: GET /odata/staff

Request Parameters

No query parameters are required for this endpoint. OData query options (e.g., $top, $skip, $filter) are supported.

Example Queries

  • To retrieve a list of all staff:

    {{BASE_URL}}odata/staff

  • Filtering with multiple operators:

    {{BASE_URL}}odata/staff?$filter=staffID gt 10 and staffID lt 21

  • Example with order by and pagination:

    {{BASE_URL}}odata/staff?$orderby=StaffID asc&$top=10&$skip=10

Response

  • Status Code: 200 OK

  • Response Body: An array of staff objects.

Example Response

[
			{
			"clientID": "12345",
			"firstName": "Jane",
			"email": "jane.doe@example.com",
			"telephone": "+441234567890",
			"suspended": false,
			"vatRegistered": true
			}
		]

Response Details

Each staff object in the array contains the following fields:

  • clientID (string): Unique identifier for the staff member.

  • firstName (string): First name of the staff member.

  • email (string): Email address of the staff member.

  • telephone (string): Telephone number of the staff member.

  • suspended (boolean): Indicates if the staff member is suspended.

  • vatRegistered (boolean): Indicates if the staff member is VAT registered.

New Endpoint: /odata/jobs

Retrieves a list of all jobs from the system.

HTTP Method: GET /odata/jobs

Authentication

Requires a valid TOKEN variable to be set for authentication.

Request Parameters

No query parameters are required for this endpoint by default. You may add OData query options (e.g., $top, $skip, $filter) as needed.

Example Requests

  • To retrieve a list of all jobs:

    {{BASE_URL}}odata/jobs

  • Filtering for a specific jobid:

    {{BASE_URL}}odata/jobs?$filter=jobID eq 25

  • Example with order by and pagination:

    {{BASE_URL}}odata/jobs?$orderby=JobID asc&$top=10&$skip=10

Response

  • Status Code: 200 OK

  • Response Body: An array of job objects.

Example Response

[
			{
			"jobID": "98765",
			"title": "Cleaner",
			"location": "London",
			"startDate": "2024-06-01T09:00:00Z",
			"endDate": "2024-06-01T17:00:00Z",
			"status": "active"
			}
		]

Response Details

Each job object in the array contains the following fields:

  • jobID (string): Unique identifier for the job.

  • title (string): Title or position of the job.

  • location (string): Location where the job is based.

  • startDate (string, ISO 8601): Start date and time of the job.

  • endDate (string, ISO 8601): End date and time of the job.

  • status (string): Status of the job (e.g., active, completed, cancelled).

New Endpoint: /odata/contacts

Retrieves a list of all contacts from the system.

HTTP Method: GET /odata/contacts

Request Parameters

No query parameters are required for this endpoint by default. OData query options (e.g., $top, $skip, $filter) are supported.

Example Requests

  • To retrieve a list of all contacts:

    {{BASE_URL}}odata/contacts

  • Filtering for contacts in a certain city:

    {{BASE_URL}}odata/contacts?$filter=city eq Birmingham

  • Example with order by and pagination:

    {{BASE_URL}}odata/contacts?$orderby=contactID asc & $top=10 & $skip=50

Response

  • Status Code: 200 OK

  • Response Body: An array of contact objects.

Example Response

[
			{
			"clientID": "12345",
			"firstName": "Jane",
			"email": "jane.doe@example.com",
			"telephone": "+441234567890",
			"suspended": false,
			"vatRegistered": true
			}
		]

Response Details

Each contact object in the array contains the following fields:

  • clientID (string): Unique identifier for the contact.

  • firstName (string): First name of the contact.

  • email (string): Email address of the contact.

  • telephone (string): Telephone number of the contact.

  • suspended (boolean): Indicates if the contact is suspended.

  • vatRegistered (boolean): Indicates if the contact is VAT registered.

Developer Notes

  • All endpoints require a valid TOKEN variable to be set for authentication.

  • Refer to the updated API documentation for the full schema.

  • Sample response payloads have been updated to include new or enhanced fields.

  • Ensure downstream systems are configured to handle and store any new fields if needed for reporting.

Backward Compatibility Maintained

Existing integrations will continue to function as expected. New fields are non-breaking and optional to consume.