> For the complete documentation index, see [llms.txt](https://help.formality.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.formality.com/integrations/api.md). # Formality API Client Documentation ### 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`](http://app.formality.com) in the APP URL. For example, if you are accessing agreements using the following URL: ``` ``` 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: 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 ``` \ 4. **Use the access token in your API requests** In the response, locate the `token` field and copy its value. ```json { "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 ``` ## 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.: ``` ``` 4. Navigate to the **Headers** tab and add the following key-value pair: * **Key:** `Authorization` * **Value:** `Bearer ` 5. Click **Send** to execute the request. 6. Review the JSON response. ### Using the Token with Curl Run the following command in your terminal: ```bash curl -X GET '' \\ -H 'Authorization: Bearer ' ``` ## Objects relationship
## Base API URL To access the API, use the following format: ``` ``` For example: ``` ``` ## 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 ``` ### Example: Retrieve Agreement Fields **Endpoint:** ``` GET /api/v1/{workspaceId}/agreementFields ``` **Example Request:** ``` GET ``` ## Handling Responses API responses are returned in JSON format. Example response for retrieving agreements: ```json { "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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.formality.com/integrations/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.