# Forms

Read-only access to the Forms app: the forms in your account and the applications (submissions) they have received.

NOTE

These endpoints are read-only. Forms are created and edited from the Wolfeo interface.

# List Forms

GET https://api.wolfeo.me/v1/forms

Returns a paginated list of the forms in your account, each with the total number of submissions it has received. Use it to discover the id to pass to /form and /form-submissions.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/forms?status=published" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
status	string	Filter by form status (see possible values below)
page	integer	Page number (default: `1`)
per_page	integer	Results per page, max `100` (default: `50`)

# Possible values for `status`

Value	Description
`draft`	Not published yet, not reachable by visitors
`published`	Live and accepting submissions
`archived`	Retired, no longer accepting submissions

# Sample Return

{
    "success": true,
    "data": [
        {
            "id": 1,
            "type": "candidature",
            "name": "Projet 2DAY",
            "status": "published",
            "submissions_count": 42,
            "created_at": "2026-06-01T09:12:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 3
    }
}

TIP

Forms are returned most recent first. submissions_count counts every submission, including the ones still in_progress.

# Possible Errors

Code	HTTP	Description
INVALID_STATUS	400	`status` is not one of `draft`, `published`, `archived`
VALIDATION_ERROR	422	Invalid `page` or `per_page`
UNAUTHORIZED	401	Invalid or missing API key

# Get Form

GET https://api.wolfeo.me/v1/form

Returns one form with its questions and its outcomes. Read it before filtering submissions on an answer: /form-submissions expects a question_id, and this is where you find it.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/form?id=1" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
id*	integer	The form id

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "id": 1,
        "type": "candidature",
        "name": "Projet 2DAY",
        "status": "published",
        "questions": [
            {
                "id": 7,
                "label": "Can a coach contact you on WhatsApp?",
                "type": "yes_no",
                "options": null
            },
            {
                "id": 8,
                "label": "What is your monthly budget?",
                "type": "single_choice",
                "options": ["Under 500", "500 to 2000", "Over 2000"]
            }
        ],
        "outcomes": [
            {
                "key": "ideal",
                "title": "Profil idéal",
                "bucket": "hot"
            }
        ]
    }
}

TIP

options is null for question types that carry no predefined choices, such as yes_no or free text. When present, it lists the option labels in display order.

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	No form with this id in your account
VALIDATION_ERROR	422	`id` is missing or not an integer
UNAUTHORIZED	401	Invalid or missing API key

# List Form Submissions

GET https://api.wolfeo.me/v1/form-submissions

Returns a paginated list of submissions. Each row carries the prospect's identity, score, qualification bucket, status and dates, but not the per-question answers, the phone number or the AI summary. Fetch those one submission at a time through /form-submission.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/form-submissions?form_id=1&bucket=hot&status=completed" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
form_id	integer	Only submissions of this form
status	string	`completed` or `in_progress`
bucket	string	`hot`, `warm` or `cold`
score_min	number	Only submissions scoring at or above this value
contact_id	integer	Only submissions linked to this contact
email	string	Only submissions whose linked contact has this email
period	string	Time range on the creation date (see possible values below)
range	string	Custom date range, only used when `period=between`
updated_after	string	Only submissions updated at or after this ISO datetime
question_id	integer	Question to filter an answer on, required by the two below
answer	string	Exact answer to that question
answer_contains	string	Substring of the answer to that question
include_attribution	boolean	Include the ad attribution object (default: `false`)
sort	string	`created_at` or `score` (default: `created_at`)
order	string	`asc` or `desc` (default: `desc`)
page	integer	Page number (default: `1`)
per_page	integer	Results per page, max `100` (default: `50`)

# Possible values for `period`

Value	Description
`all`	All submissions ever
`today`	Submissions created today
`yesterday`	Submissions created yesterday
`last7days`	Submissions created in the last 7 days
`last30days`	Submissions created in the last 30 days
`between`	Custom date range (requires `range`)

# Format for `range`

Pass two dates separated by to:

2026-06-01to2026-06-29

# Sample Return

{
    "success": true,
    "data": [
        {
            "id": 1024,
            "form_id": 1,
            "status": "completed",
            "score": 15,
            "bucket": "hot",
            "outcome_key": "ideal",
            "contact": {
                "id": 812,
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "started_at": "2026-06-12T10:02:11.000000Z",
            "completed_at": "2026-06-12T10:07:48.000000Z",
            "created_at": "2026-06-12T10:02:11.000000Z",
            "updated_at": "2026-06-12T10:07:48.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 50,
        "total": 247
    }
}

TIP

score is a raw point total, the sum of the answers' points. It is not a 0 to 100 scale, and its ceiling depends on how the form is scored. Use bucket when you need a comparable hot / warm / cold signal.

WARNING

Poll with updated_after rather than period. A submission left in_progress and completed days later keeps its original creation date, so a filter on period will never show it again, while updated_after will.

# Possible Errors

Code	HTTP	Description
INVALID_STATUS	400	`status` is neither `completed` nor `in_progress`
INVALID_BUCKET	400	`bucket` is not `hot`, `warm` or `cold`
MISSING_QUESTION_ID	400	`answer` or `answer_contains` sent without `question_id`
INVALID_PERIOD	400	Unrecognised `period`, or `between` without a valid `range`
VALIDATION_ERROR	422	A parameter has the wrong type
UNAUTHORIZED	401	Invalid or missing API key

# Get Form Submission

GET https://api.wolfeo.me/v1/form-submission

Returns the full detail of a single submission: the contact card including the phone number, the score with its resolved outcome title, the per-question answers, the AI summary and the ad attribution. This is the only endpoint that exposes the answers and the phone number.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/form-submission?id=1024" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
id*	integer	The submission id

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "id": 1024,
        "form_id": 1,
        "form": {
            "id": 1,
            "name": "Projet 2DAY",
            "type": "candidature"
        },
        "status": "completed",
        "score": 15,
        "bucket": "hot",
        "outcome_key": "ideal",
        "contact": {
            "id": 812,
            "email": "john.doe@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "+33 600000000",
            "company_name": "Doe Consulting"
        },
        "qualification": {
            "bucket": "hot",
            "outcome_key": "ideal",
            "title": "Profil idéal"
        },
        "ai_summary": "Runs a 3-person consultancy, budget above 2000, wants to start in September.",
        "attribution": {
            "utm_source": "facebook",
            "utm_campaign": "leads-june",
            "ad_id": "23861234567890123"
        },
        "answers": [
            {
                "question_id": 7,
                "label": "Can a coach contact you on WhatsApp?",
                "type": "yes_no",
                "answer": "yes",
                "score": 5
            }
        ],
        "started_at": "2026-06-12T10:02:11.000000Z",
        "completed_at": "2026-06-12T10:07:48.000000Z",
        "created_at": "2026-06-12T10:02:11.000000Z",
        "updated_at": "2026-06-12T10:07:48.000000Z"
    }
}

TIP

ai_summary is null until the summary has been generated, and completed_at is null while the submission is still in_progress.

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	No submission with this id in your account
VALIDATION_ERROR	422	`id` is missing or not an integer
UNAUTHORIZED	401	Invalid or missing API key

# What's next

Contacts : the contact each submission is linked to
Funnels : step by step stats for the pages that feed your forms

← Funnels Orders →

# Forms

# List Forms

# Example Request

# Parameters

# Possible values for status

# Sample Return

# Possible Errors

# Get Form

# Example Request

# Parameters

# Sample Return

# Possible Errors

# List Form Submissions

# Example Request

# Parameters

# Possible values for period

# Format for range

# Sample Return

# Possible Errors

# Get Form Submission

# Example Request

# Parameters

# Sample Return

# Possible Errors

# What's next

# Possible values for `status`

# Possible values for `period`

# Format for `range`