Instructions & valuations

Create an instruction

POST /api/v1/instructions

Sends a new valuation instruction to your institution’s queue, exactly as if a staff member had entered it. It starts at the first stage of your workflow and carries a remark saying it came through the API.

You need an institution key with the instructions:read_write scope. Your administrator makes one in Settings › API access.

Parameters

client_id

string · required

One of your clients, e.g. CL-981. Create the client first if it is new.

purpose

string · required

Secured Lending, Sale/purchase, Insurance, Property Tax, Rental Assessment and the other purposes in your settings. A wrong value returns the allowed list.

job_type

string · optional

The kind of job, as in your settings.

property_type

string · optional

The kind of property, as in your settings.

property.description

string · optional

Plot, block and place as the client gave them.

property.plot_number

string · optional

Plot number.

property.block_number

string · optional

Block number.

property.location

string · optional

Place name or address.

property.county

string · optional

A recognised Ugandan county name, such as Kyadondo, Busiro or Mawokota. Other values are refused.

instruction_date

date · optional

YYYY-MM-DD. Defaults to today.

external_reference

string · optional

Your own reference. Sending it again returns the existing instruction instead of a copy (header X-Idempotent-Replay: true).

Errors

401 invalid_key

The key is missing, unknown, revoked or expired.

403 ip_not_allowed

The request came from an address the key is not allowed to use.

429 rate_limited

Too many requests this minute. Wait for Retry-After seconds.

429 quota_exceeded

The monthly allowance is used up. It resets on the first of the month.

403 wrong_key

This is a comparables key. Use an institution key for this endpoint.

403 api_not_enabled

API access isn’t switched on for your institution.

403 not_in_plan

This API isn’t part of your institution’s plan. Ask ValueApps to add it.

403 insufficient_scope

The key doesn’t have the access this call needs.

404 client_not_found

The client id is not one of yours.

422 validation_failed

A field is missing or not valid; details names it and, for purpose, lists the allowed values.