Village APIs: Introduction

Common information shared across POST APIs

Jump to:

Prerequisites

An Admin Account (Invite Users & Admins ->)
A Network (Create a Network ->)
An API Key (Developer Quickstart ->)

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

Header	Value
Content-Type	application/json
Accept	application/json

Header

Value

Content-Type

application/json

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

Code	Description
201	Success: request is queued for processing.
400	Bad request: malformed request syntax or invalid request message framing.
401	Not unauthorized.
404	Not found
500	Internal server error.

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:

Field	Description
Status Symbol	Symbol indicating general success of the original request. (Green=Success, Red=Error.)
HTTP Status Code	The HTTP equivalent of the response status code associated with the original request.
Error Message	If there was a processing error, the description of the error will be listed here.
Request ID	The UUID associated with the original request response.
API Key Name	The common name of the API key.
Number of Messages Sent	Messages sent to the Village ledger associated with the original request.
Names of Messages Sent	List of names sent to the Village ledger associated with the original request.
Request Data	A copy of the data sent to Village in the original request.

Field

Description

Status Symbol

Symbol indicating general success of the original request. (Green=Success, Red=Error.)

HTTP Status Code

The HTTP equivalent of the response status code associated with the original request.

Error Message

If there was a processing error, the description of the error will be listed here.

Request ID

The UUID associated with the original request response.

API Key Name

The common name of the API key.

Number of Messages Sent

Messages sent to the Village ledger associated with the original request.

Names of Messages Sent

List of names sent to the Village ledger associated with the original request.

Request Data

A copy of the data sent to Village in the original request.

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

Code	Description
201	Success.
400	Bad request: malformed request syntax or invalid request message framing.
401	Not unauthorized.
404	The original API request has not completed processing
500	Internal server error.

Response Model

Field	Description
HTTP Status Code	The HTTP equivalent of the response status code associated with the original request.
Error Message	If there was a processing error, the description of the error will be listed here.
Request ID	The UUID associated with the original request response.
API Key Name	The common name of the API key.
Number of Messages Sent	Messages sent to the Village ledger associated with the original request.
Names of Messages Sent	List of message names sent to the Village ledger associated with the original request.
Request Data	A copy of the data sent to Village in the original request.