Overview
This guide is part of a series designed to help you build a data integration with a third‑party system using the Onefile API. Once authenticated, you may want to download existing data from Onefile to compare, sync, or map against your external system.
This guide covers:
- Retrieving the Customer record
- Finding Organisations linked to the Customer
- Downloading Assessors, Classes, Placements and Learners
- Understanding when multiple Organisations exist
- Using paged searches for more detailed fields
Next guides in this series:
- Creating and managing users via the API
- Assigning users to learners via the API
- Assigning Framework Templates, Standards and Units via the API
Base URLs
- Beta Server: https://wsapibeta.onefile.co.uk/api/v2.1
- Practice Server: https://wsapi2.onefile.co.uk/api/v2.1
- Live Server: https://wsapi.onefile.co.uk/api/v2.1
When developing an integration with the OneFile API, once authenticated via the API, you may want to download the existing data from OneFile.
To do this, follow the guidance below:
Get CustomerID
GET https://wsapibeta.onefile.co.uk/api/v2.1/Customer
Response:
{
"ID": 2070,
"Name": "Example Beta Customer"
}
Get Organisations linked to the Customer
POST https://wsapibeta.onefile.co.uk/api/v2.1/Organisation/search
Body:
{
"CustomerID": 2070
}
Response:
[
{
"ID": 5740,
"Name": "Example Organisation - Business",
"KeychainCreationForNewUserActive": false,
"KeychainEmailSuppression": false
},
{
"ID": 5741,
"Name": "Example Organisation - Care",
"KeychainCreationForNewUserActive": false,
"KeychainEmailSuppression": false
}
]
Multiple Organisations
Most customers will only have one organisation linked to their customer record. However, some may have multiple centres, where they require complete separation of data and access.
Get Assessors in an Organisation
POST https://wsapibeta.onefile.co.uk/api/v2.1/User/Search/1/10
Body:
{
"OrganisationID": 5740
"Role": 5,
}
Response:
[
{
"ID": 122762,
"FirstName": "James",
"LastName": "Fayre"
"MISID": "JFAYE51P"
},
{
"ID": 132757,
"FirstName": "Kate",
"LastName": "Anderson"
"MISID": "KANDREWS142"
}
]
Get Classes in an Organisation
POST https://wsapibeta.onefile.co.uk/api/v2.1/Classroom/Search
Body:
{
"OrganisationID": 5740
}
Response:
[
{
"ID": 15379,
"Name": "Business Admin L2",
"MISID": "BAD1"
},
{
"ID": 15381,
"Name": "Business Admin L3",
"MISID": "BAD2"
},
]
Get Placements in an Organisation
POST https://wsapibeta.onefile.co.uk/api/v2.1/Placement/Search
Body:
{
"OrganisationID": 5740
}
Response:
[
{
"ID": 18928,
"Name": "BT - Manchester"
"MISID": "BT54810A"
},
{
"ID": 18929,
"Name": "Vodaphone - Salford",
"MISID": "VP0491045X"
}
]
Get Learners in an Organisation
POST https://wsapibeta.onefile.co.uk/api/v2.1/User/Search
Body:
{
"OrganisationID": 5740
"Role": 1
}
Response:
[
{
"ID": 137945,
"FirstName": "Gemma"
"LastName": "Hall"
"MISID": "GHALL391"
},
{
"ID": 137946,
"FirstName": "Chloe"
"LastName": "Henshall"
"MISID": "CHENSHALL194"
},
]
Using This Data
Once you have downloaded the base data, you can compare against your external system to identify:
- Existing records in both systems
- Users requiring updates
- New users needing creation
- Entities requiring MISID alignment
For detailed user information (ULN, NINO, email, etc.), use the Paged User Search endpoints. This allows cleaner matching and enables updating MISIDs via the Update endpoints.
Next Guide
→ Creating and Managing Users via the API
Terminology
Terminology may differ depending on your Centre or system configuration.
Need Help?
If you require help with API usage or integration support, please contact Onefile Support or your internal technical team.