Formality API Client Documentation

The Formality API Client allows you to interact with the Formality API efficiently, providing endpoints to manage agreements, counterparties, and related entities within a given workspace.

Requirements

• An active Formality workspace.

• The base API URL.

• Your assigned workspaceId, which follows /api/v1/ in the API URL.

---

Identifying Your Workspace ID

The workspaceId follows app.formality.com in the APP URL. For example, if you are accessing agreements using the following URL:

<https://app.formality.com/myCompany/agreements>

The workspace ID is myCompany.

Accessing the Swagger Interface

To explore and test the API, you can use the Swagger UI.

Steps to Access Swagger:

1. Open your browser.

2. Navigate to the following URL: https://app.formality.com/-/api-doc-swagger

3. The Swagger UI will load (you must be logged in), displaying the available API endpoints.

4. You can expand any endpoint to view details and test API calls.

5. Click Try it out on an endpoint to enter parameters and execute requests.

6. Review the responses directly in the interface.

Generating Personal Refresh Tokens

Refresh Tokens let you securely connect your Formality workspace to external tools and services like Postman, scripting environments, or internal integrations—without needing to log in manually.

What You Can Do With Refresh Tokens

Automate Workflows

Use tokens to enable integrations that automate tasks like syncing agreements or triggering actions based on lifecycle events.

Access the API Securely

Generate access tokens to authenticate API requests without sharing your login credentials.

Monitor and Manage Usage

See when and where your tokens were last used, helping you stay in control of access.

Set Expirations

Define how long a token stays valid—from a few days to a full year—and revoke it at any time.

Steps to Generate a Token:

1. Create a Refresh Token Head to Personal Settings > Formality API

   1. click on “New Token”

   2. give it a name

   3. set a token description if needed

   4. set an expiration date

   5. click on “Create Token”

2. Use It Once to Save It The full token is shown only once right after creation—copy and store it somewhere safe. Once copied you can click on “Done”

3. Generate the Access Token Once you’ve copied your refresh token, you can use it to request an Access Token via the GET /api/v1/token endpoint.

   Authorization: Bearer <your-refresh-token>

   <aside> ℹ️

   The access token has a lifespan of 5 minutes, once expired you’ll need to generate a new one.

   </aside>

4. Use the access token in your API requests In the response, locate the token field and copy its value.

   {
     "token": "THIS_IS_THE_TOKEN_TO_COPY"
   }

You can use this access token to request all the endpoints by adding the following header:

Authorization: Bearer <your-access-token>

Using the Token in External Tools

Once you have the token, you can use it in other tools like Postman or Curl to authenticate API requests.

Using the Token in Postman

1. Open Postman.

2. Create a new request.

3. Select the GET method and enter an API endpoint, e.g.:

   <https://app.formality.com/api/v1/myCompany/agreements>

4. Navigate to the Headers tab and add the following key-value pair:

   • Key: Authorization

   • Value: Bearer <your-access-token>

5. Click Send to execute the request.

6. Review the JSON response.

Using the Token with Curl

Run the following command in your terminal:

curl -X GET '<https://app.formality.com/api/v1/myCompany/agreements>' \\
	-H 'Authorization: Bearer <your-access-token>'

Objects relationship

Base API URL

To access the API, use the following format:

<https://app.formality.com/api/v1/{workspaceId}/>

For example:

<https://app.formality.com/api/v1/myCompany/>

Making API Requests

All requests should be made using the correct HTTP methods (GET, POST, PUT, DELETE) and must include the required workspaceId.

Example: Retrieve Agreements

Endpoint:

GET /api/v1/{workspaceId}/agreements

Example Request:

GET <https://app.formality.com/api/v1/myCompany/agreements>

Example: Retrieve Agreement Fields

Endpoint:

GET /api/v1/{workspaceId}/agreementFields

Example Request:

GET <https://app.formality.com/api/v1/myCompany/agreementFields>

Handling Responses

API responses are returned in JSON format. Example response for retrieving agreements:

{
  "agreements": [
    {
      "id": "cm7ymby3b0009uh08ytb7zo",
      "name": "Sample Agreement",
      "status": "active"
    }
  ]
}

Error Handling

Status Code	Meaning
401	Unauthorized – Check your access rights.
403	Forbidden – Ensure you have the correct permissions.
404	Not Found – Verify the workspace ID and endpoint.
500	Internal Server Error – Contact support if the issue persists.

Conclusion

This API client allows seamless integration with the Formality system. Ensure that you use the correct workspaceId and handle responses and errors properly when making API requests.

---

Need Help?

If you run into any issues or have questions about the API, reach out to our Customer Success team. We’re happy to guide you through the setup or help troubleshoot.