Village APIs: Introduction
Common information shared across POST APIs
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:
Headers
Content-Type
application/json
Accept
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
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:
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
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
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.
Last updated
