Service Endpoints - JSON API
Table of Contents
- Introduction
- Request Information
- GET Brand Services
- GET Incorporation Services
- GET Service
- Object Definitions
- Request Filters
- Statuses
1.0 Introduction
eFiling has different endpoints that allows API users to interact with services.
Services are created from products that are ordered in the eFiling system, a service can be linked to a user, company or officer.
2.0 Request Information
HTTP GET
All service endpoints have optional parameters that can be passed in the request URL. These can be used to filter the result set returned, if no filters are sent then the API will return all records.
The results will be paginated and limited to 100 per result set.
The filters will remain the same for all service endpoints
Example:
/brands/service/?status=700/company/1234/services/?status=700
Please See Request Filters for a list of parameters
3.0 GET /brands/services
This end point will return an array of all services created in the system.
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service objects |
| pagination | object | Pagination details |
| errors | array | Contains an array of strings |
4.0 GET /company/[incorporation-id]/services
This end point will return an array of services created/assigned to an Incorporation/Company.
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service objects |
| pagination | object | Pagination details |
| errors | array | Contains an array of strings |
6.0 GET /services/[service-id]
This end point can be used to retrieve one service.
This response will return an array of services but the array will only contain one result.
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service objects |
| pagination | object | Pagination details |
| errors | array | Contains an array of strings |
7.0 Object definitions
7.1 Pagination
An object that contains details about pagination
| Property | Value | Description |
|---|---|---|
| result_count | int | The number of results returned. |
| result_total | int | The total number of results available. |
| current_page | int | The page you are viewing based on the result_limit being displayed. Passed in through the URL |
| total_pages | int | The total number of pages you can view. |
7.2 Request
An object that returns details about API request.
'filters' will only be returned when 'debug' is set to '1'
| Property | Value | Description |
|---|---|---|
| type | string | HTTP method |
| url | string | Endpoint requested. |
| filters | object | An object containing any applied filters. |
7.3 Response
An object that contains the data requested.
| Property | Value | Description |
|---|---|---|
| services | array | an array of service objects |
7.4 Service
| Property | Value | Description |
|---|---|---|
| id | int | The id of the service. |
| user_id | int | The id of the user this service belongs to. |
| incorporation_id | int | The id of the incorporation this service belongs to. |
| officer_id | int | The id of the officer this service belongs to. |
| product_id | int | The id of the product this service is related to. |
| renew_date | int | The renewal date in the format YmdHis. |
| date_created | int | The created date in the format YmdHis. |
| date_updated | int | The date updated in the format YmdHis. |
| date_cancelled | int | The date cancelled in the format YmdHis. |
| cancelled_by | int | The id of the user this was cancelled by. |
| auto_renew | boolean | If the service will auto renew. |
| status | int | The status of the service. |
| status_text | string | The status of the service as a text description. |
| incorporation_name | string | The name of the incorporation this service belongs to. |
| product_name | string | The product name of servuce. |
| officer_type | string | person or corporate |
| officer_corporate_name | string | The name of the corporate officer |
| officer_firstname | string | The first name of person officer or corporate authoriser |
| officer_lastname | string | The last name of person officer or corporate authoriser |= |
| user_organisation | string | If the user account is a company. ie an accountant |
| user_firstname | string | The first name of the user this service belongs to. |
| user_lastname | string | The last name of the user this service belongs to. |
| user_email | string | The email of the user this service belongs to. |
8.0 Request Filters
Here are a list of filters that can be passed to 'services' end points
Please note all dates are represented as a 14 digit number '20170801235959' (YmdHis)
| Value | Type | Description |
|---|---|---|
| debug | int | 1 or 0; enables debug info in response |
| page | int | The page number you want to view, defaulted to 1. |
| limit | int | The limit of results you receive, default/max is 100. |
| status | int | The status of results you receive. |
| auto_renew | bool | If autorenew has been turned on or not. |
| created_from | int | Filter the results, showing anything created from this date. |
| created_to | int | Filter the results, showing anything created to this date. |
| renew_from | int | Filter the results, showing anything renewed from this date. |
| renew_to | int | Filter the results, showing anything renewed to this date. |
| cancelled_from | int | Filter the results, showing anything cancelled from this date. |
| cancelled_to | int | Filter the results, showing anything cancelled to this date. |
9.0 Statuses
These statuses can then be used to filter down your response.
| Status | Status Text |
|---|---|
| 0 | Inactive service |
| 25 | Expired service that requires action |
| 26 | Cancelled service that requires action |
| 700 | Active service |
| 750 | Paused service |
| 900 | Service expired |
| 950 | Service cancelled |
**requires action - a form needs to be filied at Companies House
**paused service - pending MLC checks
**expired service - user has chosen not to renew
**cancelled service - user has cancelled the service or failed to renew due to invalid payment details
Glossary
Brand - a website hosted on the eFiling platform
User - refers to a customer user account that has been registered
Service - also known as a subscription, services in eFiling are products that are purchased and renewed periodically.