Your application should use the GraphQL endpoint at https://api.xsortal.com:4001

All API requests should send an Authorization header along with your API key:

Authorization: Bearer d445Ug1lk7

Your API limits won't start until you perform your first API request. To help you get setup you can use our test API key as seen below:

Authorization: Bearer 123456789abcdefg

The test API key is unlimited and allows you to test your setup before switching to your live key. The test key will not return real-life grant results and will always return the same two sample grant results no matter which of the 4 limited queries (see below) you request.

Grants API – 5 Minute Matcher

We have a minimal HTML/CSS/JS code example that creates a basic grants matcher in a few minutes. You can view the code here: Grants API – 5 Minute Matcher

API limits are only applied on those queries which return grant results i.e.:

• allPurposes
• purpose
• grant
• relatedGrants

The API imposes limits based on your level of subscription package. The limits are imposed based on two metrics:

Number of unique requests per month x Number of results returned per request

Definition of a unique request

A unique request is any unique combination of arguments passed to any of the API limited queries listed above. Should you request a query using a combination of arguments that you've already used in the last month then results will be returned as normal and there will be no impact on your API limit count.

The following arguments have no effect on your API limit: orderBy, orderByDirection, perPage, currentPage

Should you exceed your API limit then you will receive the below as a response:

{
  "data": {
      "apiError": "You have reached your monthly API limit"
  }
}

Monitoring your API limits

The below X-API Response Headers are sent with every response:

Name	Description	Example
x-api-max-monthly-requests	How many unique requests your subscription alows per month	20
x-api-max-results-per-request	The maximum number of results returned per unique request	20
x-api-total-unique-requests-this-month	How many unique requests have been made this month	2
x-api-total-unique-requests-remaining-this-month	How many unique requests are remaining this month	18
x-api-start-date	When your first request was made	Tue Mar 11 2022 07:38:14 GMT+0100
x-api-limit-start-date	When your current API limit period started	11/02/2023, 07:38:14
x-api-limit-end-date	When your current API limit period will end	11/03/2023, 07:38:14

Our grants database contains thousands of grant. Each grant is broken down into various Funding Purposes. A single grant can have 1 or more Funding Purposes. A Funding Purpose is essentially the part of a grant that someone can apply to get money for.

It is recommended that your searches and results revolve around Funding Purposes rather than the overall encompassing grants as users apply for money at the Funding Purpose level.

Some examples of Funding Purposes are:

• Business Growth
• Job Creation
• Staff Development
• Working Capital

The full list of Funding Purposes can be obtained through the allFundingPurposes GraphQL query.

The main query you use to return a set of Funding Purpose results is allPurposes

The main query you use to return a single Funding Purpose result is purpose

Grant specific fields

Field	Type	Description	Example
id	integer	Unique number to identify the grant	62
url	string	The URL of the grants home page	https://www.cofundni.com
title	string	The title of the grant	Co-Fund NI Business Investment
open_or_closed	enum	Is the grant Open, Opening, Closed or Closing	Opening
currency	enum	The currency the grant amount is in ('£', '€', '$')	£
total_fund_size	integer	The size of the overall pot of money available across the grant's purposes - unformatted	50000000
total_fund_size_formatted	string	The size of the overall pot of money available across the grant's purposes - formatted	5,000,000
provider_1	string	The main provider of the grant	Invest Northern Ireland
provider_2	string	The secondary provider of the grant	Clarendon Fund Managers
provider_3	string	The tertiary provider of the grant	European Commission
funding_types	array	The types of funding provided	Equity Finance
purposes	array	The available purposes for the grant. See below for the Purpose specific fields	Business Growth
date_added	integer	The timestamp of when the grant was added into our database	1678705244

Funding Purpose specific fields

Field	Type	Description	Example
id	integer	Unique number to identify the purpose	204796
grant_id	integer	The id of the grant this purpose is attached to	62
funding_purpose	string	The type of funding purpose	Business Growth
funding_purpose_definition	string	Definition of the funding purpose	Business growth grants fund activities that help you increase sales or find new customers such as market research, marketing, website translation or the cost of launching a product.
purpose_title	string	The title of the purpose	Co-Fund NI Business Investment
purpose_url	string	The URL of the purpose's home page	http://www.cofundni.com
purpose_application_url	string	The URL of the purpose's application page	https://www.cofundni.com/company-application-form.aspx
purpose_size_min	integer	The minimum amount available for this purpose - unformatted	150000
purpose_size_min_formatted	integer	The minimum amount available for this purpose - formatted	150,000
purpose_size_max	integer	The maximum amount available for this purpose - unformatted	1000000
purpose_size_max_formatted	integer	The minimum amount available for this purpose - formatted	1,000,000
purpose_description	string	Description of the purpose	The Co-Fund NI programme aims to invest alongside private investors such as business angels or business angel syndicates into eligible SMEs.
purpose_dates	string	Contains the relevant date or dates of the purpose. Could also display, for example, Ongoing if there are no relevant dates	Start Date for Applications: 9th January 2023 Application Deadline: 19th March 2023
purpose_region_is_uk	integer	Does this purpose cover the whole of the UK? 1=true 0=false	0
deadline_date	integer	Timestamp, if any, of the purpose's deadline date	1679184000
date_added	integer	The timestamp of when the purpose was added into our database	1678705244
regions	array	The regions this purpose applies to	North West South East
sectors	array	The sectors this purpose applies to. Can also show "All Sectors" if the purpose isn't sector specific	Construction Manufacturing
business_types	array	The business types this purposes applies to	Small Business Medium Business

When using the allPurposes query to fetch results there is a default ordering that takes place to ensure the results returned are the most relevant ones. The default ordering occurs under the following conditions:

1. No orderBy specified but a sector argument is specified
2. orderBy is '"sector"
3. No orderBy specified but a location/region is specified
4. orderBy is "region" or "location"

Sector ordering

Sector ordering occurs for the following examples:

query {
  allPurposes(sector: "Construction") {
    ...
  }
}

1st level ordering	2nd level ordering	Comment
1. exact sector match DESC 2. sectors including the given sector DESC 3. All Sectors DESC	purpose_size_max DESC	Results only assigned to the given sector(s) are returned first, followed by those results that are assigned to more than 1 sector(s) including the given sector, followed by those sectors assigned to no specific sector (All Sectors). Results within each sector result group are ordered by purpose_size_max DESC

query {
  allPurposes(
    funding_purpose: "Business Innovation"
    orderBy: "sector"
    ) {
    ...
  }
}

In this example, as no sector was specified but orderBy is "sector", results are returned in sector alphabetical order with those assigned to All Sectors coming after those with an assigned sector.

Location/Region ordering

Location or region ordering occurs for the following examples:

query {
  allPurposes(location: "Dudley") {
    ...
  }
}

1st level ordering	2nd level ordering	Comment
region DESC	purpose_size_max DESC	Results are returned in location heirarchy order (Town -> City -> LGA -> County -> NUTS -> Country). In the example above results will be returned in the order where region matches Dudley -> Dudley District -> West Midlands -> England -> United Kingdom. Within each of those region levels results are ordered by purpose_size_max DESC

query {
  allPurposes(
    funding_purpose: "Business Innovation"
    orderBy: "location") {
    ...
  }
}

In this example, as no location was specified but orderBy is "location", results are returned in location heirarchy order (Town -> City -> LGA -> County -> NUTS -> Country) with those assigned to the whole of the UK coming at the end.

If you ONLY wanted the Dudley results returned, and not any results from the region heirarchy, you can use the locationOnly argument of the allPurposes query. When locationOnly is passed and set to 1, ONLY extact region matches are returned, in this example only results for Dudley would be returned.

10th April 2024

• Documented how the default ordering works when there's no orderBy specified.

2nd April 2024

• Added a new Location option which expands on the Region field by providing a list of locations right down to town level, you should use either the allRegions query or the allLocations query depending on the level of details you want to use. To get a list of all possible locations you can use the new allLocations query. The allPurposes query also now has a location argument you can use instead of the region argument.

24th January 2024

• Added a new query, allSectorSICCodes which will return a full list of Standard Industrial Classification codes and how they are mapped to our industry sectors.

15th January 2024

• Added a new field called funding_purposes to the allPurposes query. This is essentially the same as the funding_purpose field but it accepts an array of values that allows you to pass more than one funding purpose, for example, ["Business Growth", "Business Innovation"]. You can either use funding_purpose for a single funding purpose query or funding_purposes for one or more funding purposes queries though eventually we'll deprecate the funding_purpose field as the new funding_purposes field caters for all situations. Click here to view the funding_purposes details in the API documentation