Village APIs: Introduction
Common information shared across POST APIs
Last updated
Was this helpful?
Common information shared across POST APIs
Last updated
Was this helpful?
An Admin Account ()
A Network ()
An API Key ()
Explore the . 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.
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
The base URL for all API endpoints is:
Content-Type
application/json
Accept
application/json
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.
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.
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:
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.
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.
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.
URL
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.
Due to our system's asynchronous processing architecture and cryptographically verifiable ledger, our POST APIs utilize an and a 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 were fully processed without errors.
The same and are required as with POST requests
GET
