Charity law is changing. Click here to find out how the changes will affect your charity.

OSCR Public APIs

In May 2023, OSCR launched a BETA version of an API to communicate data from the Scottish Charity Register.

The guidance below will help you to set up the API. There are two calls available through the API: one to get all charities, and one to get up to 5 years annual returns for a particular charity.

https://oscrapi.azurewebsites.net/api/all_charities

Authorisation API Key

Add as Header Value

  • Key: x-functions-key
  • Value: <value>

Query Params

  • page: 10
  • charitynumber: SC000001

Note: The query parameters are not mandatory.
Note: If both page and charitynumber are requested, the page parameter is ignored.

Example Request

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get,
"https://oscrapi.azurewebsites.net/api/all_charities");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Example Response

json 
{   
"currentPage": 1,
    "totalPages": 26,
    "prev": null,
    "next": "https://oscrapi.azurewebsites.net/api/all_charities?page=2",
    "data": [
        {
            "id": "afead305-90b5-ec11-983f-00224800a357",
            "charityName": "Stoneyburn Community Education Centre Assoc",
            "charityNumber": "SC000001",
            "registeredDate": "1986-06-26",
            "knownAs": null,
            "website": null,
            "parentCharityName": null,
            "parentCharityNumber": null,
            "parentCharityCountryOfRegistration": null,
            "designatedReligiousBody": false,
            "charityStatus": "Active",
            "currentConstitutionalForm": "7 unincorporated association",
            "notes": null,
            "geographicalSpread": "1 A specific local point, community or neighbourhood",
            "mainOperatingLocation": "West Lothian",
            "purposes": [
                "B - the advancement of education"
            ],
            "beneficiaries": [
                "f. No specific group, or for the benefit of the community"
            ],
            "typesOfActivities": [
                "b. It makes grants, donations or gifts to organisations",
                "c. It carries out activities or services itself"
            ],
            "objectives": "The objects of the Association are:- (a) To advance education and to provide, or assist in the provision of, facilities for recreation or other leisure-time occupation, where such provision or assistance in provision -  (i) is in the interests of Social, Welfare; and (ii) is made with the object of improving the conditions of life of the members of the community in the area of benefit;  and for those purposes to associate with the Lothian Regional Council (hereinafter referred to as \"the Council\", voluntary organisations and inhabitants in the area of benefit. (b) To co-operate with the Council and its successors in office in establishing, maintaining and managing any Community Centre situate in the area of benefit which is provided or grant-aided by the Council in so far as it is established, maintained and managed for the attainment or object (a) of the Association.",
            "regulatoryType": null,
            "charityType": null,
            "postcode": "EH47 8BY",
            "principalOfficeOrTrusteeAddress": "Principal",
            "mostRecentYearIncome": 620,
            "nextYearEndDate": "2022-03-31",
            "mailingCycle": "2021",
            "yearEnd": "2021-03-31",
            "mostRecentYearExpenditure": 2898
        }
    ]
}

https://oscrapi.azurewebsites.net/api/annualreturns?charityid=7e464432-f13e-ed11-bba2-0022481b519e

Authorisation API Key

Add as Header Value

  • Key: x-functions-key
  • Value: <value>

Query Params

  • charityid: 7e464432-f13e-ed11-bba2-0022481b519e

Example Request

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get,
"https://oscrapi.azurewebsites.net/api/annualreturns?charityid=7e464432-f13e-ed11-bba2-0022481b519e");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Example Response

json
 [
    {
        "UniqueReference": "SC051899.2022.1",
        "CharityNumber": "SC051899",
        "AccountingReferenceDate": "2022-10-06",
        "GrossIncome": 0,
        "GrossExpenditure": 0,
        "ReceivedDate": null,
        "DonationsAndLegaciesIncome": 0,
        "CharitableActivitiesIncome": 0,
        "OtherTradingActivitiesIncome": 0,
        "InvestmentsIncome": 0,
        "OtherIncome": 0,
        "RaisingFundsSpending": 0,
        "CharitableActivitiesExpenditure": 0,
        "OtherExpenditure": 0,
        "TotalNumberofCharityTrustees": 0,
        "PaidStaff": 0
    },
    {
        "UniqueReference": "SC051899.2021.1",
        "CharityNumber": "SC051899",
        "AccountingReferenceDate": "2021-10-06",
        "GrossIncome": 1870000,
        "GrossExpenditure": 450000,
        "ReceivedDate": "2022-09-28",
        "DonationsAndLegaciesIncome": 0,
        "CharitableActivitiesIncome": 0,
        "OtherTradingActivitiesIncome": 0,
        "InvestmentsIncome": 0,
        "OtherIncome": 0,
        "RaisingFundsSpending": 0,
        "CharitableActivitiesExpenditure": 0,
        "OtherExpenditure": 0,
        "TotalNumberofCharityTrustees": 5,
        "PaidStaff": 11
    }
]

400 Bad Request:

An error message signifying the error will be thrown.

401 Unauthorized:

Ensure the API key is added to the header and is correct.

404 Not Found:

This might occur if the Charity contents are null, or if no Annual Returns are present for the given Charity ID.

503 Service Unavailable:

This might occur during charity data refresh. Takes 2-3 minutes to be back.

We regularly make changes to the API to improve the features and functionality. You can see the latest updates below:

14/07/2023: Update to the GET All Charities call

A new field has been added to the call, 'principalContactAddress'. This field will provide the public address of the charity, minus the postcode, held by OSCR, where we can make this public. If are do not make this public, the field will show 'Address Withheld'.

14/07/2023: Update to the GET Annual Returns for a Charity

Two new fields have been added to the call. 

  • CharityProvidedLinkToAccount. If the charity has provided a link to their annual accounts on their website, this will be shown as 'True', if not, 'False'.
  • LinkToCharityAccount. If they have provided a link to their annual accounts, the link will be shown here. If not, the value will be 'null'