Village APIs: Introduction

Common information shared across POST APIs

Prerequisites

  1. An Admin Account (Invite Users & Admins ->)

Explore with our Postman Collection

Explore the Village API collection with Postman. Postman allows you to see the Village API in action, copy/paste code snippets in multiple languages, and test different integrations live. We highly recommend using this resource while integrating with Village.

Authentication

To use this API, you must generate an API Key from Village. The API key should be supplied in an Authorization header with the token, preceded by Bearer:

Authorization: Bearer API_KEY

API URL

The base URL for all API endpoints is:

https://api-ledger.villagelabs.net/

Headers

Metadata

For Village’s API, many of our objects also have an optional metadata object that can be updated. Metadata can be used to store additional structured information about an object. For instance, you can store a transaction’s unique identifier from your system on an Activity object in our API. By default, metadata is not used by our API or the Village System to execute Rule logic, but it can be queried through our analytics tools and in our Search API (coming soon). Note that users won't see metadata unless you choose to display it to them.

Metadata also usually includes a description parameter, which can be used to add a human-readable description to an object. E.g., "2 shirts for test@example.com."

We strongly advise you not to store any sensitive information such as bank account numbers or card details in the metadata.

POST Request Response & Errors

For POST requests, the response body will contain a JSON object representing whether or not the POST request was successfully added to Village's asynchronous processing queue.

Response status codes

Read Me! On Asynchronous Responses:

Due to our system's asynchronous processing architecture and cryptographically verifiable ledger, our POST APIs utilize an API Results Table and a GET Results API to display errors and other information related to API requests.

The real-time response code you do receive from a Village POST API request represents whether or not your request has been added to our asynchronous processing queue, not whether the POST request and any downstream Programs & Rules were fully processed without errors.

To view downstream processing errors and other information related to your POST requests, use the API Results Table in the Admin Dashboard or the GET Results API.

API Results Table

To access the frontend view of API request results table view, visit Network Home -> API Keys & Documentation.

For each POST Request, the following information will be available in the API Results Table:

GET Results API

Querying the API Results

If you prefer to use an API query instead of viewing the processing results via the Admin Dashboard, you may also make a GET request from the Results API to retrieve the processing status of a POST API Request.

  • The GET Results API is synchronous and responses are immediate.

  • The same authentication and headers are required as with POST requests

URL

GEThttps://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/results/ID

  • Replace 'YOUR_NETWORK_ID' with your actual Network ID

  • Replace 'ID' with the 'request_id' you received in the original POST response

Response Codes

Response Model

Last updated