> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Submit an application

POST https://api-sandbox.payabli.com/api/v2/requests/{requestsReference}/submit
Content-Type: application/json

Submits a draft application for review. Your integration (the applicant) calls this after the business, its people, payment methods, and services are in place. Verification then runs automatically.

The application must have a signer: an owner flagged with `isSigner` on their business link, or one you name in `signer.personReference`. Payabli records the signer's identity from their person record and business link, so update those before you submit. The `signer` object carries the signature details.

If the application has no signer, the request fails with `422` and the error `SIGNER_REQUIRED`. If `signer.personReference` names a person who isn't an owner, the request fails with `422` and the error `SIGNER_NOT_OWNER`. If the application isn't a draft, the request fails with `409` and the error `BIZ_004`, before any signer check. If `signer.reportedSignerIp` isn't a single valid IPv4 or IPv6 address, the request fails with `400` and the error `VALIDATION_ERROR`, and the application isn't submitted.

Submit doesn't check every rule that [validate](/developers/api-reference/applications/validate-an-application) reports, such as the primary controller and ownership rules. Validate the application and resolve its missing fields before you submit.


Reference: https://docs.payabli.com/developers/api-reference/applications/submit-an-application

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api-sandbox.payabli.com/api` (Sandbox, default)
- `https://api.payabli.com/api` (Production)

## Request

### Path parameters

- `requestsReference` (string, required) — The application reference.

### Body (application/json)

This endpoint expects a SubmitApplicationRequest.

- `signer` (SubmitSigner, required) — The signature details for the application's signer, and optionally which person signs.

## Response

### 200

The action succeeded. The response returns the application's new status and allowed actions.

- `success` (boolean, required) — Whether the request succeeded.
- `message` (string, required, nullable) — A human-readable result message.
- `traceId` (string, required, nullable) — The trace identifier for the request, useful for support.
- `data` (TransitionResult, required, nullable) — The lifecycle-action result.

## Errors

### 400 Bad Request Error

The request is invalid, for example because `signer.reportedSignerIp` isn't a single valid IP address. The application isn't submitted.

- `success` (boolean, required) — Whether the request succeeded. Always `false`.
- `error` (string, required) — The error code, such as `VALIDATION_ERROR`, `SIGNER_REQUIRED`, or `SIGNER_NOT_OWNER`.
- `message` (string, required) — A human-readable description of the error.
- `traceId` (string, required, nullable) — The trace identifier for the request, useful for support.

### 401 Unauthorized Error

Unauthorized request.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 404 Not Found Error

The requested resource wasn't found.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 409 Conflict Error

The request conflicts with the current state of the resource.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 422 Unprocessable Entity Error

The application has no signer (`SIGNER_REQUIRED`), or the person named in `signer.personReference` isn't an owner (`SIGNER_NOT_OWNER`).

- `success` (boolean, required) — Whether the request succeeded. Always `false`.
- `error` (string, required) — The error code, such as `VALIDATION_ERROR`, `SIGNER_REQUIRED`, or `SIGNER_NOT_OWNER`.
- `message` (string, required) — A human-readable description of the error.
- `traceId` (string, required, nullable) — The trace identifier for the request, useful for support.

### 500 Internal Server Error

Internal server error.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

## Types

### SubmitSigner

The signature details for the application. The signer is the person flagged with `isSigner` on the business, and Payabli records the signer's identity from their person record and business link. Keep the signer's details current with the people endpoints before you submit, because you can't correct them here. Provide a signature with `signature` and `signatureType`, or, if the signer signed in your own e-sign tool, send `signedDocumentReference` instead. Signer identity fields such as `name`, `email`, `ssn`, and `address` aren't part of this object, and Payabli ignores them if you send them.

- `personReference` (string, optional) — The reference of an owner linked to this business, to make them the signer before the application is submitted. Works only while the application is a draft. Leave it out when the business already has a signer. If the person isn't linked to this business, the request fails with `404`. If the person isn't an owner, the request fails with `422` and the error `SIGNER_NOT_OWNER`.
- `signature` (string, optional) — The signature. For `type` and `checkbox`, send the signer's name. For `draw`, send the image as a base64 data URL, such as the output of `canvas.toDataURL()`. Required unless you send `signedDocumentReference`.
- `signatureType` (enum, optional) — How the signer signed. Required with `signature`.
  - Allowed values: `type`, `draw`, `checkbox`
- `signedDocumentReference` (string, optional) — The reference for a document the signer signed in your own e-sign tool, such as a DocuSign envelope ID. Send it instead of `signature` and `signatureType`.
- `acceptance` (boolean, optional) — Whether the signer accepted the terms. If you leave it out, Payabli records `false`.
- `pciAttestation` (boolean, optional) — Whether the signer attested to PCI compliance. If you leave it out, Payabli records `false`.
- `reportedSignerIp` (string, optional) — The IP address of the signer's device, as your system saw it. Payabli records it as reported by you, in its own field, and still records the IP address it observes on the request. Send a single IPv4 address in dotted-decimal form, such as `203.0.113.7`, or an IPv6 address in any valid form, up to 45 characters. Payabli rejects ports, CIDR ranges, IPv6 zone IDs, lists of addresses, and shorthand, integer, hex, or leading-zero IPv4 forms. An invalid value returns `400`, and the application isn't submitted. An empty value is treated as not sent.
- `additionalData` (map from string to string, optional) — Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. If you are using [custom identifiers](/developers/developer-guides/entities-customers), pass those in this object. Max length for a value is 100 characters. ```json { "additionalData": { "key1": "value1", "key2": "value2", "key3": "value3" } } ```

### TransitionResult

The result of a lifecycle action, with the application's new status.

- `requestsReference` (string, required) — The application reference.
- `applicationStatus` (string, required) — The application's lifecycle status after the action. See the application object for the list of statuses.
- `allowedActions` (list of string, required) — The lifecycle actions now allowed on the application. The list can include actions that Payabli or its internal services perform, which you can't call through the API.

### PayabliErrorBodyResponseData

Object with detailed error context.

- `explanation` (string, optional) — Human-readable explanation of what happened.
- `todoAction` (string, optional) — Suggested resolution.

## Examples

### SubmitApplication

**Request**

```json
{
  "signer": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  }
}
```

**Response**

```json
{
  "success": true,
  "message": "Application submitted",
  "traceId": "0HNONVRI1SMEU:0000068E",
  "data": {
    "requestsReference": "3f3caa7b-bdfe-4bf1-814b-30d54859247c",
    "applicationStatus": "submitted",
    "allowedActions": [
      "startVerification",
      "withdraw",
      "abandon",
      "markError"
    ]
  }
}
```

**SDK Code**

```python SubmitApplication
import requests

url = "https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit"

payload = { "signer": {
        "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
        "signature": "Marcus J Delgado",
        "signatureType": "type",
        "acceptance": True,
        "pciAttestation": True,
        "reportedSignerIp": "203.0.113.7"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript SubmitApplication
const url = 'https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"signer":{"personReference":"01a0014d-ce1a-7110-9bac-c4c59647a88d","signature":"Marcus J Delgado","signatureType":"type","acceptance":true,"pciAttestation":true,"reportedSignerIp":"203.0.113.7"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go SubmitApplication
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit"

	payload := strings.NewReader("{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby SubmitApplication
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java SubmitApplication
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}")
  .asString();
```

```php SubmitApplication
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit', [
  'body' => '{
  "signer": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp SubmitApplication
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift SubmitApplication
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["signer": [
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### SubmitNewLocationApplication

**Request**

```json
{
  "signer": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  }
}
```

**Response**

```json
{
  "success": true,
  "message": "Application submitted",
  "traceId": "0HNP8M4GTH3IP:0000001B",
  "data": {
    "requestsReference": "b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406",
    "applicationStatus": "submitted",
    "allowedActions": [
      "startVerification",
      "withdraw",
      "abandon",
      "markError"
    ]
  }
}
```

**SDK Code**

```python SubmitNewLocationApplication
import requests

url = "https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit"

payload = { "signer": {
        "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
        "signature": "Marcus J Delgado",
        "signatureType": "type",
        "acceptance": True,
        "pciAttestation": True,
        "reportedSignerIp": "203.0.113.7"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript SubmitNewLocationApplication
const url = 'https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"signer":{"personReference":"01a0014d-ce1a-7110-9bac-c4c59647a88d","signature":"Marcus J Delgado","signatureType":"type","acceptance":true,"pciAttestation":true,"reportedSignerIp":"203.0.113.7"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go SubmitNewLocationApplication
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit"

	payload := strings.NewReader("{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby SubmitNewLocationApplication
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java SubmitNewLocationApplication
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}")
  .asString();
```

```php SubmitNewLocationApplication
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit', [
  'body' => '{
  "signer": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp SubmitNewLocationApplication
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"signer\": {\n    \"personReference\": \"01a0014d-ce1a-7110-9bac-c4c59647a88d\",\n    \"signature\": \"Marcus J Delgado\",\n    \"signatureType\": \"type\",\n    \"acceptance\": true,\n    \"pciAttestation\": true,\n    \"reportedSignerIp\": \"203.0.113.7\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift SubmitNewLocationApplication
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["signer": [
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/submit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```