---
title: "Lead Form API Documentation"
description: "The Lead Form API allows you to retrieve your lead form schema and submit enquiry forms programmatically into Agentcis. Using a bearer token for authentication, you can access the form fields, validate required inputs, and send structured payloads (including custom fields and test scores) directly via API. This helps automate lead capture from websites, apps, or third-party platforms into your Agentcis"
url: https://support.agentcis.com/en/articles/392-lead-form-api-documentation
collection: "API Documentation"
updated: 2026-11-12
language: en
---

# Lead Form API Documentation

The Lead Form API allows you to retrieve your lead form schema and submit enquiry forms programmatically into Agentcis. Using a bearer token for authentication, you can access the form fields, validate required inputs, and send structured payloads (including custom fields and test scores) directly via API. This helps automate lead capture from websites, apps, or third-party platforms into your Agentcis

## **Step 1: Obtain Bearer Token**

1.  Go to [yourdomain.agentcisapp.com](http://yourdomain.agentcisapp.com).
    
2.  Navigate to Settings > API & Integrations.
    
3.  Access the API tab and create a new token.
    
4.  Copy the generated token; this will serve as your bearer token.
    

## **To Retrieve the Slug of Your Lead Form** 

1.  Open your lead form.
    
2.  Copy the text following "/online-form/" from the URL; this is the slug of your lead form.
    

Example:

For the URL `https://demo.agentcisapp.com/online-form/social-media-form`, the slug is `social-media-form`.

## **To Access Lead Form Schema**

URL: `https://{yourdomain}.agentcisapp.com/api/v2/online-form/{slug}/docs`

-   Replace `{yourdomain}` with your Agentcis subdomain.
    
-   Replace `{slug}` with the slug obtained from the previous step.
    

**Example Response:**

HTTP Method: GET

Status: 200

Headers:

```javascript
{
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer {your bearer token from step 1}"
}

```

Response Body: 

```javascript
[
  {
    "id": 469,
    "name": "first_name",
    "is_required": true,
    "slug": "first_name",
    "type": "string"
  },
  {
    "id": 470,
    "name": "last_name",
    "is_required": true,
    "slug": "last_name",
    "type": "string"
  },
  {
    "id": 471,
    "name": "date_of_birth",
    "is_required": true,
    "slug": "date_of_birth",
    "type": "date"
  },
  {
    "id": 472,
    "name": "phone",
    "is_required": false,
    "slug": "phone",
    "type": "string"
  },
  {
    "id": 473,
    "name": "email",
    "is_required": false,
    "slug": "email",
    "type": "string"
  },
  {
    "id": 474,
    "name": "secondary_email",
    "is_required": false,
    "slug": "secondary_email",
    "type": null
  },
  {
    "id": 475,
    "name": "contact_preference",
    "is_required": false,
    "slug": "contact_preference",
    "type": "string"
  },
  {
    "id": 476,
    "name": "street",
    "is_required": false,
    "slug": "street",
    "type": "string"
  },
  {
    "id": 477,
    "name": "city",
    "is_required": false,
    "slug": "city",
    "type": "string"
  },
  {
    "id": 478,
    "name": "state",
    "is_required": false,
    "slug": "state",
    "type": "string"
  },
  {
    "id": 479,
    "name": "postal_code",
    "is_required": false,
    "slug": "postal_code",
    "type": "string"
  },
  {
    "id": 480,
    "name": "country",
    "is_required": false,
    "slug": "country",
    "type": "string"
  },
  {
    "id": 483,
    "name": "country_of_passport",
    "is_required": false,
    "slug": "country_of_passport",
    "type": "string"
  },
  {
    "id": 1,
    "name": "TOEFL",
    "is_required": false,
    "slug": "TOEFL",
    "meta": null,
    "bands": [
      {
        "id": 1,
        "name": "Listening",
        "is_required": false
      },
      {
        "id": 2,
        "name": "Reading",
        "is_required": false
      },
      {
        "id": 3,
        "name": "Writing",
        "is_required": false
      },
      {
        "id": 4,
        "name": "Speaking",
        "is_required": false
      }
    ]
  },
  {
    "id": 2,
    "name": "IELTS",
    "is_required": false,
    "slug": "IELTS",
    "meta": null,
    "bands": [
      {
        "id": 5,
        "name": "Listening",
        "is_required": false
      },
      {
        "id": 6,
        "name": "Reading",
        "is_required": false
      },
      {
        "id": 7,
        "name": "Writing",
        "is_required": false
      },
      {
        "id": 8,
        "name": "Speaking",
        "is_required": false
      }
    ]
  },
  {
    "id": 3,
    "name": "PTE",
    "is_required": false,
    "slug": "PTE",
    "meta": null,
    "bands": [
      {
        "id": 9,
        "name": "Listening",
        "is_required": false
      },
      {
        "id": 10,
        "name": "Reading",
        "is_required": false
      },
      {
        "id": 11,
        "name": "Writing",
        "is_required": false
      },
      {
        "id": 12,
        "name": "Speaking",
        "is_required": false
      }
    ]
  },
  {
    "id": 4,
    "name": "SAT I",
    "is_required": false,
    "slug": "SAT I",
    "meta": null,
    "bands": []
  },
  {
    "id": 5,
    "name": "SAT II",
    "is_required": false,
    "slug": "SAT II",
    "meta": null,
    "bands": []
  },
  {
    "id": 6,
    "name": "GRE",
    "is_required": false,
    "slug": "GRE",
    "meta": null,
    "bands": []
  },
  {
    "id": 7,
    "name": "GMAT",
    "is_required": false,
    "slug": "GMAT",
    "meta": null,
    "bands": []
  },
  {
    "id": 497,
    "name": "dropdown-custom-field",
    "type": "dropdown",
    "slug": "e2d24773-e171-4e8f-ba0f-f34efb1ef038",
    "is_required": false,
    "meta": null,
    "is_custom_field": true,
    "items": [
      "aaa",
      "aa"
    ]
  },
  {
    "id": 498,
    "name": "text-type-custom-field",
    "type": "text",
    "slug": "7ca31d9e-adc6-46f7-987c-a4b231623888",
    "is_required": false,
    "meta": null,
    "is_custom_field": true,
    "items": []
  }
]

```

## **To Submit a Lead Form**

HTTP Method: POST

URL: `https://{yourdomain}.agentcisapp.com/api/v2/online-form/{slug}/`

Headers:

```javascript
{
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer {your bearer token from step 1}"
}

```

Payload:

payload format

`{`

`"slug" : "value"`

`}`

Example Payload 1 with test score

```javascript

{
	"first_name": "chandan",
	"last_name": "sharma",
	"e2d24773-e171-4e8f-ba0f-f34efb1ef038": [
		"aaa",
		"aa"
	],
	"date_of_birth": "2020-09-11",
	"phone": {
		"number": "9843617001",
		"country_code": "NP"
	},
	"country": "nepal",
	"country_of_passport": "nepal",
    "comments": "Some comments"
}

```

**Response:**

Status: 200

Response Body:

```javascript
{
    "message": "Successfully submitted enquiry form",
    "data": {
        "id": 1,
        "name": "lead name lead last name"
    }
}

```

* * *

Please replace placeholders like `{yourdomain}`, `{slug}`, and other relevant values with your actual information.

Example Payload 2 with test score

```javascript
{
	"first_name": "chandan",
	"last_name": "office",
	"email": "chandan.sharma@globalyhub.com",
	"form_id": 3,
	"test_scores": [
		{
			"test_id": 2, // test id
			"score": 1 //overall test score
		},
		{
			"test_id": 3, // test id
			"score": 2, // overall test score
			"bands": [ // score by bands. These fields are only available on enabling "Enable all individual fields" in form setting
				{
					"id": 9,
					"score": 2
				},
				{
					"id": 10,
					"score": 2
				},
				{
					"id": 11,
					"score": 3
				},
				{
					"id": 12,
					"score": 3
				}
			]
		},
		{
			"test_id": 4,
			"score": 3
		},
		{
			"test_id": 5,
			"score": 3
		},
		{
			"test_id": 6,
			"score": 3
		},
		{
			"test_id": 7,
			"score": 3
		}
	]
}

```

## Fetch Country List

Retrieve a comprehensive list of countries with currency information, supporting search functionality for dynamic dropdowns and form selections.

<table data-id="67df1576-b5c7-4a44-8682-7a846e85451a" style="min-width: 25px;"><colgroup><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; border-width: 1pt; border-style: solid; border-color: #000000;"><p data-id="d9afe0a3-c0f3-45f4-b945-429505dec82b"><span style="color: rgb(0, 0, 0);"><strong>Base URL: </strong>https://{tenant-domain}/api/countries</span></p><p data-id="d9e21776-6f69-4cdb-918d-5ca17a8c7c5b"><br></p><p data-id="b7254f60-2e30-4ecc-a879-b150405823e3"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></p></td></tr></tbody></table>

### List Countries

-   Endpoint:/
    
-   Method: GET
    
-   Description:Lists countries and it’s description like currency code and many more
    

  
**Response**:

<table data-id="922b7531-a2a0-425e-8c19-923aee24ff68" style="min-width: 25px;"><colgroup><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; border-width: 1pt; border-style: solid; border-color: #000000;"><p data-id="21c0f49d-9ac4-44ff-a19f-c5dc9475f2ed"><span style="color: rgb(0, 0, 0);">[</span></p><p data-id="3fb9c1b5-9c77-472a-96ad-60b91b4f95c8"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;{</span></p><p data-id="f42cdb1d-c47c-4b5e-b371-57d135bbe546"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"id": 1,</span></p><p data-id="4a9bab9f-45ec-468c-87c4-3617d2e56710"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_name": "Australia",</span></p><p data-id="4b286175-e5ca-4343-869d-91371445d464"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_code": "AUD",</span></p><p data-id="1e50b8ab-c0a9-4571-afa1-0156d775cad9"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_name": "Australian Dollar",</span></p><p data-id="f06c32fd-a72d-43e7-af19-4bf7d0be13da"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_dialing_code": "61",</span></p><p data-id="533ea85e-1a75-4004-814b-310810b67c07"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"value": "Australia - AUD [Australian Dollar]"</span></p><p data-id="89785512-ae73-4497-8dda-0af5ee2e23e7"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;},</span></p><p data-id="068a4c0d-f4aa-4a96-b2b6-9ac83996abc7"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;{</span></p><p data-id="003f2c1e-4ac0-4913-87c0-592c1bdab55b"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"id": 2,</span></p><p data-id="52f81797-0caa-4a63-a8a4-3abd1a41626c"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_name": "United States",</span></p><p data-id="a26da10e-23e1-432c-b04d-43b4b8e003b7"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_code": "USD",</span></p><p data-id="3a0fbedb-d54f-433c-9154-a15c81878977"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_name": "US Dollar",&nbsp;</span></p><p data-id="8779abfc-1155-4111-a1a7-ba951434b873"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_dialing_code": "1",</span></p><p data-id="77524184-4102-4a17-8801-17f0443259d8"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"value": "United States - USD [US Dollar]"</span></p><p data-id="8811673b-27d4-4956-880c-b60b758c1368"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;},</span></p><p data-id="3880387b-5cd9-4dd5-86b6-fe4aa2a1ba8f"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;{</span></p><p data-id="03c41d2d-ae9a-463d-b1b3-087255a1108a"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"id": 3,</span></p><p data-id="eb64a1e9-01f8-4c0b-8ed7-3b46abccee28"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_name": "United Kingdom",</span></p><p data-id="4267fd17-64ff-48f2-bbf2-8ddd50ac0f90"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_code": "GBP",</span></p><p data-id="d8a14c91-6538-45a8-811c-786466ff8ab4"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"currency_name": "British Pound Sterling",</span></p><p data-id="79503df8-c09b-4278-a397-4b33f63ed5f7"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"country_dialing_code": "44",</span></p><p data-id="7c75cf8b-7d7a-41f2-b05a-344bddd1d254"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;"value": "United Kingdom - GBP [British Pound Sterling]"</span></p><p data-id="20a8dcff-86f0-457d-a715-10f8b5c323ad"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;}</span></p><p data-id="c0639350-efbd-405c-8b25-b36837ab0e1f"><span style="color: rgb(0, 0, 0);">….</span></p><p data-id="735b298d-43da-4f7c-b1a3-1fc6979f5007"><span style="color: rgb(0, 0, 0);">]</span></p></td></tr></tbody></table>

### Formatted List of countries Countries 

-   Endpoint:/list?keyword={character}
    
-   Method: GET
    
-   Description:Lists countries also supports wildcards for searching specific country
    
-   country\_name is a parameter which accepts country name and fetch specific country
    
-   Endpoint:/list?keyword=Austr
    

**Response**:

<table data-id="53bdd9c1-2a32-4bfe-9786-1f937c9c137a" style="min-width: 25px;"><colgroup><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; border-width: 1pt; border-style: solid; border-color: #000000;"><p data-id="e4fe4a06-f88d-4b10-8c85-3c08810789b4"><span style="color: rgb(0, 0, 0);">[</span></p><p data-id="15b7d918-eb1b-4233-868a-0ad65ee99afd"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;{</span></p><p data-id="cc4cc1bc-70b5-4bcb-a9a6-e7e522f12615"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"id": 11,</span></p><p data-id="810de1bc-4ee4-4f2c-a666-f8e59edb7fab"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_name": "Australia",</span></p><p data-id="bd5c95d4-5282-4968-a68f-6c0fdd6562cf"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"currency_name": "Australian dollar",</span></p><p data-id="4fb26a41-9bc0-4fee-8a8d-03f04308a0d6"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"currency_code": "AUD",</span></p><p data-id="ec1ffce5-b177-4886-90df-10d3dc705216"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_code": "AU",</span></p><p data-id="d75b3cd4-fb38-4bbb-80ea-526e2333af73"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_dialing_code": "61",</span></p><p data-id="e973f0e8-5284-4faa-a5db-e585e1671f19"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_code_iso_alpha3": "AUS",</span></p><p data-id="d80c9125-5ec2-46e4-830f-33cd8d2a2e33"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"value": "Australia"</span></p><p data-id="90d6188e-1fde-4c69-bdd6-3da235e71ad4"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;},</span></p><p data-id="0106f6cf-f7cf-445d-9c5a-35fcdfb68b9d"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;{</span></p><p data-id="80fb4fe4-410b-41dd-b7fa-dcb3b8088849"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"id": 12,</span></p><p data-id="4850bb12-12b8-40f5-a5f3-c07a7a414bbd"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_name": "Austria",</span></p><p data-id="7b63e55a-2f32-40fa-aa9c-cc149a0f12f3"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"currency_name": "euro",</span></p><p data-id="5a513e6c-5cd5-4d56-80b3-8be4e304c044"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"currency_code": "EUR",</span></p><p data-id="639692cf-b597-4380-aef6-6bebbe29eff2"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_code": "AT",</span></p><p data-id="422e05cd-7545-473b-be0a-32b156f4ea28"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_dialing_code": "43",</span></p><p data-id="6797a15a-dc5e-4cdd-8b36-37e54e7c8841"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"country_code_iso_alpha3": "AUT",</span></p><p data-id="f98258a3-a257-4f69-a188-7b0aec149794"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"value": "Austria"</span></p><p data-id="a3799abd-ebc6-403b-9a7c-0ec72eabc65f"><span style="color: rgb(0, 0, 0);">&nbsp;&nbsp;&nbsp;&nbsp;}</span></p><p data-id="b41bbbf8-a422-4e54-8821-e04da0e50eab"><span style="color: rgb(0, 0, 0);">]</span></p></td></tr></tbody></table>
