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. A new login issues a new GUID; treat expiry as the only documented invalidation.
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. |
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.
Agent webhooks send
applicationRef (the tenancy) and, on applicant events,
data.applicantRef.
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.