Identifiers and environments
Persist BOX identifiers in your CRM as you create records. There is no list or search endpoint: if you lose a reference, you cannot recover the case through this API.
Environments
| Environment | Base URL |
|---|---|
| Pre-production | https://pre-prod.lettingshub.co.uk/webapi/v2 |
| Production | Issued per partner. Not published here. |
Credentials are a BOX user that belongs to the branches you will use. The same username is not valid across environments unless you were given both.
Token
POST /Authenticate sets response headers Token
(a GUID) and TokenExpiry (minutes). Lifetime is 720 minutes
(12 hours). Send it as request header Token. Header names
are case-insensitive.
When a call returns 401, authenticate again and retry. Every successful login issues a new GUID and retires every earlier token for the same user, so two processes that share one BOX user will log each other out. Run one session per user and share its token, or give each integration its own user.
What to store
| Name in paths | What it is | Shape |
|---|---|---|
BranchId |
Branch from GET /Branches (Id) |
Integer, e.g. 4 |
ApplicationRef / ReferenceNumber |
The tenancy. Returned as a JSON string from create tenancy. | Seven-digit id, e.g. 00013524 |
TenantRef / GuarantorRef / ApplicantRef / Reference |
One person on that tenancy. On the applicant object as ReferenceNumber. |
Agent prefix + seven-digit id, e.g. s0013524, AL00013524. Self-service drafts are prefixed DY. |
ExternalReference |
Your CRM’s id, optional, set on create. | Your string. This is the join key; BOX will not list cases by it. |
Agent webhooks send
applicationRef (the tenancy) and, on applicant events,
data.applicantRef.
Deprecated Notifications send the
applicant reference as ReferenceNo, not
the application reference. Store applicant → application when you
create the tenant, or you cannot call
GET /Applications/{ApplicationRef}/{Reference} or fetch a
report from a notification alone.
Path overlap
POST /Applications/{BranchId} and
GET /Applications/{ReferenceNumber} share a URL template.
The POST parameter is a branch integer; the GET parameter is the
tenancy reference string. Do not send a tenancy ref to create, or a
branch id to fetch.