Developer docs

Guide

How Fence's API works

What Fence does with the data you send, the asset program everything belongs to, your ids and Fence's, and who may call what.

Fence keeps your book of assets and works out how each one is paying. Your systems send what happened: the assets, how they are meant to be repaid and the money that moved. Fence stores each batch exactly as you sent it, checks every record against your program's rules, and works out each asset's schedule, what each payment paid and the asset's state.

Everything belongs to an asset program

An asset program is one set of your assets with the rules Fence applies to them: its time zone, the currencies it allows and the shape of your records. You may have several, for example one per country or product. Every call names its program in the path, and everything you send and read belongs to exactly one program.

  • A submission is one batch you sent, stored as received. See Submissions and records.
  • A record is one line of a batch. Fence decides each record on its own.
  • Assets, asset groups, payment plans and payments are what your records declare.
  • Expected payments, allocations and the asset state are what Fence works out from them. You read them; you never send them.

Your ids and Fence's ids

Two kinds of id appear in every answer:

  • Your id names a thing as your systems do: asset_id, payment_id, asset_group_id. Records find what they change by your id.
  • Fence's id is the id in every answer, a UUID that never changes. It is the id in a route's path, such as /assets/{id}.

To go from your id to Fence's, list with a filter:

curl -s "$FENCE_API/v1/api/asset-programs/$PROGRAM_ID/assets?asset_id=L-123" \
  -H "Authorization: Bearer $TOKEN"

Who may call what

Your system calls the API with a token from its integration: the client_id and client_secret Fence gave you. The Quickstart shows how to get one. A token lasts 45 minutes.

Two checks decide each call:

  1. Scope, in the token: portfolio:read for every read, submissions:write to send a batch.
  2. Grant, on the asset program in the path: read, or write, which includes read.

Answer

When

401

No token, or an expired one. Get a new token.

403

The token lacks the route's scope, or you sent a batch to a program you may only read.

404

The program does not exist or is not yours. Both give the same answer, so nobody learns which ids exist.

A new grant or a removed one reaches your calls within a minute.

Where to go next