# Using The FormWise API

{% embed url="<https://youtu.be/Oik6e7creA8?si=Y9_PrekiI3R4DGZX>" %}

## Form Completion

## POST a Form Completion to Formwise

{% openapi src="/files/pQPIhErKEI2IbfUmA1qL" path="/wf/form\_completion" method="post" %}
[form\_completion.yaml](https://728196400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Lugni2T5TewiPeYs1ka%2Fuploads%2Fl01a9q76yN3cEci51fBz%2Fform_completion.yaml?alt=media\&token=3cdedbc5-c843-4d7f-98d0-01478c0ce181)
{% endopenapi %}

#### Headers

| Name                                            | Type               | Description                                           |
| ----------------------------------------------- | ------------------ | ----------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer \<YOUR-KEY> | Your API Token which can be found on the Account page |

#### Request Body

| Name                                            | Type                                       | Description                                                                                                                                                                                                   |
| ----------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| form\_id<mark style="color:red;">\*</mark>      | "1679493702554x213757137604050940"         | The Live Form ID of the Form you are processing the responses with.                                                                                                                                           |
| answer\_array<mark style="color:red;">\*</mark> | \["Yes","No","Maybe","Certainly","Unsure"] | <p>An array of answers which represent the form response. Ensure the order of the answers matches the order of the questions on your form. Example: \["Yes","No","Maybe","Certainly","Unsure"]</p><p><br></p> |

{% tabs %}
{% tab title="200: OK Returns the Response ID of the response if successfully created." %}

{% endtab %}

{% tab title="400: Bad Request See Errors Below" %}

{% endtab %}
{% endtabs %}

After a successful POST, you will see the form response within your Live form responses. You will also receive your own email which is used to reference the account when using Zapier.

#### Example Response

```
{
    "Response ID": "1689116584424x991255285110145000"
}
```

## Retrieve Response

Retrieve Response request is used when you want to retrieve the results of a form submission.

## GET a Response Result from Formwise

<mark style="color:blue;">`GET`</mark> `https://app.formwise.ai/api/1.1/wf/retrieve_response/ID=<response id>`

Making this GET request will request the results of a response. The Formwise API is async so we recommend waiting for the content to generate before initiating this API call as you will receive an error otherwise.

#### Path Parameters

| Name                                 | Type   | Description                                                                                                                      |
| ------------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| ID<mark style="color:red;">\*</mark> | Object | The ID of the response returned from the [Form Completion API](#form-completion) call. Ensure there are no quotes around the ID. |

#### Headers

| Name                                            | Type               | Description                                           |
| ----------------------------------------------- | ------------------ | ----------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer \<YOUR-KEY> | Your API Token which can be found on the Account page |

{% tabs %}
{% tab title="200: OK Returns the response along with all generated content." %}

{% endtab %}
{% endtabs %}

## Retrieve Form IDs

The Retrieve Form IDs request is used when you want to retrieve a list of your Form IDs for use in subsequent API calls. This API is not entirely required as you can always copy the Form ID from the URL once you share your Live form within your Dashboard or on the Form Builder.

## GET all Form IDs

<mark style="color:blue;">`GET`</mark> `https://app.formwise.ai/api/1.1/wf/form_retrieval`

This operation will retrieve your Live forms in pagination (25 at once) form.

#### Headers

| Name                                            | Type               | Description                                           |
| ----------------------------------------------- | ------------------ | ----------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer \<YOUR-KEY> | Your API Token which can be found on the Account page |

{% tabs %}
{% tab title="200: OK Returns list of Live Forms available for use." %}

{% endtab %}
{% endtabs %}

After a successful GET, you will receive an array of your Live Forms along with their ID which is necessary for a [#form-completion](#form-completion "mention"), along with its Title in the event you want to store this ID and want to reference it later.

#### Example Response

```json
[ 
  {
    "_id": "1679493702554x213757137604050940",
    "title": "Marketing Feedback Form"
    },
  {
    "_id": "1679493702554x994703839005245400",
    "title": "Facebook Ad Generator"
    }
]
```

## Errors

The Data API runs on certain conditions which may throw errors when you try to Upload form data or Retrieve information about your forms. The most common error will be a 400 Error. There a few things this could mean and ways to remedy them.

* Your Monthly Quota has been exceeded and you cannot process any additional Form Responses.
  * Upgrade your account to a higher tiered plan.
* You are using a Preview Form ID when it should be a Live Form ID.&#x20;
  * Use the [Retrieve Form ID GET request](#get-all-form-ids) and select a Form or Share a form on your dashboard and copy the ID from the URL.
* Your Account is Locked due to a subscription cancellation.
  * Update your account standing by navigating to the home page and updating your payment settings.&#x20;

## Not returning a Response but no error

If you are not receiving a response upon Form submission, it is possible that the form ID you provided was not created by the user whose account Token is associated with the API call. If you are a collaborator, we recommend using the Token of the Parent account of your organization.


---

# Agent Instructions: 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:

```
GET https://manual.formwise.ai/formwise/integrations/formwise-api/using-the-formwise-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.