PayComp API

Postman collection → OpenAPI spec →

Introduction

Official API documentation for PayComp API.

Base URL: http://localhost:8000

Welcome to the PayComp API documentation.

API Stats

Total documented endpoints: 94
Authenticated endpoints: Most endpoints require a Bearer JWT token.
API version: v1

Use this manual to integrate PayComp as your Pay-As-You-Go engine, not just as a standalone product.

Who this is for

This API is designed for carriers, agencies, and integration teams that want to launch their own branded pay-as-you-go experience while using PayComp's core processing and document intelligence behind the scenes.

What you can build

White-label workflows with your own logo and front-end experience.
Document intake pipelines where files are uploaded, parsed through PayComp's core system, and returned with structured output.
End-to-end policy and payroll integrations using secure, role-based API access.

How to use this guide

Use grouped endpoints to navigate by workflow:

Inbound data and document submission.
Processing status and retrieval (pull).
Updates, replacements, and cleanup actions (including delete flows).

Security

PayComp API is protected with multiple security layers:

Rate limiting to prevent abuse and protect platform stability.
Token-based authentication (JWT).
Permission-based authorization for role and endpoint access control.
Request validation and standardized error responses for safer integrations.
Password reset email flows that redirect users to your configured frontend.

Quickstart Demo

Use this 5-minute flow to test your integration end-to-end.

Authenticate and get a token.
Create a file resource.
Fetch the created file.
Log out and revoke your session.

# 1) Login
curl -X POST "https://pcapi.ddns.net/api/v1/login" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "email": "dev@example.com",
        "password": "password123"
    }'

Copy the returned token from data.tokens.jwt (or data.tokens.access_token) and use it in the next calls. Login responses also include data.tokens.token_type and data.tokens.expires_in so clients can schedule proactive refresh.

When a session needs to stay alive, call POST /api/v1/refresh with the current bearer token, then replace the stored JWT with the new data.tokens.jwt (or data.tokens.access_token) value immediately. Refresh can be used after access-token expiry while still inside the configured refresh window.

Password Reset Flow

The API also exposes public password recovery endpoints:

POST /api/v1/forgot-password
POST /api/v1/reset-password

Forgot-password always returns the same success message to avoid revealing whether an account exists.

Reset email notifications build the link using APP_FRONTEND_URL:

{APP_FRONTEND_URL}/reset-password?token=...&email=...

Your frontend should read those query parameters and send them to POST /api/v1/reset-password with the new password.

# 2) Create a file
curl -X POST "https://pcapi.ddns.net/api/v1/files" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "name": "demo.txt",
        "content": "This is a demo payload from the Quickstart section."
    }'

# 3) Fetch the file by ID returned above
curl -X GET "https://pcapi.ddns.net/api/v1/files/1" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"

# 4) Logout
curl -X POST "https://pcapi.ddns.net/api/v1/logout" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"

Authenticating requests

To authenticate requests, include a Authorization header with the value "{YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Retrieve a token by calling POST /api/v1/login and use data.tokens.jwt (or data.tokens.access_token) as Authorization: Bearer <token>. Login and refresh both return data.tokens.access_token, data.tokens.jwt, data.tokens.token_type, and data.tokens.expires_in. Use POST /api/v1/refresh to rotate the JWT, including when the access token is expired but still within the configured refresh window. Public password recovery is available through POST /api/v1/forgot-password and POST /api/v1/reset-password, with reset links generated from APP_FRONTEND_URL.

Refresh endpoint handoff summary: POST /api/v1/refresh with Authorization: Bearer {current_token}. Response fields are in the standard envelope at data.tokens.access_token, data.tokens.token_type, and data.tokens.expires_in.

Authentication

APIs for user authentication using JWT.

POST

http://localhost:8000

/api/v1/login

Authenticate a user and issue a JWT token.

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

string

required

User email address.

Example:

dev@example.com

password

string

required

User password.

Example:

password123

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/login" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"dev@example.com\",
    \"password\": \"password123\"
}"

Example response:

{
    "data": {
        "user": {
            "id": 1,
            "name": "Dev User",
            "email": "dev@example.com"
        },
        "tokens": {
            "access_token": "<jwt-token>",
            "jwt": "<jwt-token>",
            "token_type": "bearer",
            "expires_in": 3600
        }
    },
    "message": "Login successful",
    "errors": null
}

Forgot Password

POST

http://localhost:8000

/api/v1/forgot-password

Request a password reset link by email.

For security, this endpoint always returns a generic success message to prevent account enumeration.

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

string

required

User email address.

Example:

dev@example.com

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/forgot-password" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"dev@example.com\"
}"

Example response:

{
    "data": null,
    "message": "If your email exists in our system, a password reset link has been sent.",
    "errors": null
}

Reset Password

POST

http://localhost:8000

/api/v1/reset-password

Reset account password using a valid reset token.

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

token

string

required

Password reset token from email.

Example:

7f7d9d4f0d...

string

required

User email address.

Example:

dev@example.com

password

string

required

New password.

Example:

NewStrongPassword123!

password_confirmation

string

required

Password confirmation.

Example:

NewStrongPassword123!

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/reset-password" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"token\": \"7f7d9d4f0d...\",
    \"email\": \"dev@example.com\",
    \"password\": \"NewStrongPassword123!\",
    \"password_confirmation\": \"NewStrongPassword123!\"
}"

Example response:

{
    "data": null,
    "message": "Password has been reset successfully.",
    "errors": null
}

Refresh JWT Token

POST

http://localhost:8000

/api/v1/refresh

Rotate the provided JWT and return a fresh access token.

This endpoint supports expired access tokens, as long as they are still inside the configured JWT refresh window.

Headers

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/refresh" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "tokens": {
            "access_token": "<jwt-token>",
            "jwt": "<jwt-token>",
            "token_type": "bearer",
            "expires_in": 3600
        }
    },
    "message": "Token refreshed successfully",
    "errors": null
}

User Logout

POST

http://localhost:8000

/api/v1/logout

requires authentication

Invalidate the currently authenticated JWT token.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/logout" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": null,
    "message": "Logged out successfully",
    "errors": null
}

Carriers

APIs for managing carrier resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/carriers/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

Resolve Carrier Submission Form Metadata

GET

http://localhost:8000

/api/v1/carriers/submission/{carrier_id}

requires authentication

Return carrier/driver submission metadata used by UI test-submit flows.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

carrier_id

integer

required

Carrier ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/submission/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "carrier": {
            "id": 1,
            "name": "UPS",
            "driver_id": 1
        },
        "driver": "CSV Parser",
        "submission_mode": "SFTP"
    },
    "message": "OK",
    "errors": null
}

Submit Carrier Test File

POST

http://localhost:8000

/api/v1/carriers/test_submit/{carrier_id}

requires authentication

Upload a single file and submit it to the carrier destination.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

multipart/form-data

Example:

application/json

URL Parameters

carrier_id

integer

required

Carrier ID.

Example:

Body Parameters

file

required

File to submit to the carrier.

Example:

/tmp/phpv4k2tekv3sa39S6nnEI

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/carriers/test_submit/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "file=@/tmp/phpv4k2tekv3sa39S6nnEI"

Example response:

{
    "data": {
        "status": true
    },
    "message": "Submission completed successfully.",
    "errors": null
}

Get Carrier Formatter Fields

GET

http://localhost:8000

/api/v1/carriers/formatter-fields/{carrier_id}

requires authentication

Return formatter fields for the given carrier.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

carrier_id

integer

required

The ID of the carrier.

Example:

carrier

integer

required

Carrier ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/formatter-fields/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "fields": [
            {
                "name": "employee_id",
                "label": "Employee ID"
            }
        ]
    },
    "message": "OK",
    "errors": null
}

List Carrier SFTP Remote Files

GET

http://localhost:8000

/api/v1/carriers/sftp/remotedir/{carrier_id}

requires authentication

Show remote directory files available on the carrier's SFTP destination.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

carrier_id

integer

required

The ID of the carrier.

Example:

carrier

integer

required

Carrier ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/sftp/remotedir/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "files": [
            "inbound_20260415.csv"
        ],
        "carrier": {
            "id": 1,
            "name": "UPS",
            "driver_id": 1
        }
    },
    "message": "OK",
    "errors": null
}

Download Carrier SFTP Remote File

GET

http://localhost:8000

/api/v1/carriers/sftp/download/{carrier_id}/{filename}

requires authentication

Download one file from the carrier's remote SFTP directory.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

carrier_id

integer

required

The ID of the carrier.

Example:

filename

string

required

Remote file name.

Example:

inbound_20260415.csv

carrier

integer

required

Carrier ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/sftp/download/1/inbound_20260415.csv" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "Binary file stream returned."
}

Build Carrier SFTP GPG Preview

POST

http://localhost:8000

/api/v1/carriers/sftp/gpg/{carrier}

requires authentication

Build and return SFTP/GPG formatted file preview content.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

multipart/form-data

Example:

application/json

URL Parameters

carrier

integer

required

Carrier ID.

Example:

Body Parameters

file

required

Source file used to build preview content.

Example:

/tmp/phpn1niv63aomt82JVYbvX

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/carriers/sftp/gpg/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "file=@/tmp/phpn1niv63aomt82JVYbvX"

Example response:

{
    "message": "Text preview stream returned."
}

List Carriers

GET

http://localhost:8000

/api/v1/carriers

requires authentication

Retrieve a paginated list of carriers.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "UPS",
            "driver_id": 1
        }
    ],
    "message": "OK",
    "errors": null
}

Create Carrier

POST

http://localhost:8000

/api/v1/carriers

requires authentication

Create a new carrier.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Carrier name.

Example:

UPS

driver_id

integer

Driver ID.

Example:

settings

object

required

Carrier settings object.

Host

string

required

SFTP host (key match is case-insensitive).

Example:

sftp.example.com

Root

string

required

Remote root directory path (key match is case-insensitive).

Example:

/inbound

Username

string

required

SFTP username (key match is case-insensitive).

Example:

paycomp_user

Password

string

required

SFTP password (key match is case-insensitive).

Example:

secret123

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/carriers" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"UPS\",
    \"driver_id\": 1,
    \"settings\": {
        \"Host\": \"sftp.example.com\",
        \"Root\": \"\\/inbound\",
        \"Username\": \"paycomp_user\",
        \"Password\": \"secret123\"
    }
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "UPS",
        "driver_id": 1
    },
    "message": "Created",
    "errors": null
}

Show Carrier

GET

http://localhost:8000

/api/v1/carriers/{id}

requires authentication

Retrieve a specific carrier.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the carrier.

Example:

carrier

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/carriers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "UPS",
        "driver_id": 1
    },
    "message": "OK",
    "errors": null
}

Update Carrier

PUT

PATCH

http://localhost:8000

/api/v1/carriers/{id}

requires authentication

Update an existing carrier.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the carrier.

Example:

carrier

integer

required

Example:

Body Parameters

name

string

Carrier name.

Example:

UPS

driver_id

integer

Driver ID.

Example:

settings

object

Carrier settings object.

Host

string

required_with:settings SFTP host (key match is case-insensitive).

Example:

sftp.example.com

Root

string

required_with:settings Remote root directory path (key match is case-insensitive).

Example:

/inbound

Username

string

required_with:settings SFTP username (key match is case-insensitive).

Example:

paycomp_user

Password

string

required_with:settings SFTP password (key match is case-insensitive).

Example:

secret123

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/carriers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"UPS\",
    \"driver_id\": 1,
    \"settings\": {
        \"Host\": \"sftp.example.com\",
        \"Root\": \"\\/inbound\",
        \"Username\": \"paycomp_user\",
        \"Password\": \"secret123\"
    }
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "UPS",
        "driver_id": 1
    },
    "message": "OK",
    "errors": null
}

Delete Carrier

DELETE

http://localhost:8000

/api/v1/carriers/{id}

requires authentication

Delete a carrier.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the carrier.

Example:

carrier

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/carriers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": null,
    "message": "Deleted",
    "errors": null
}

Clients

APIs for managing client resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/clients/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/clients/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Clients

GET

http://localhost:8000

/api/v1/clients

requires authentication

Retrieve a paginated list of clients.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/clients?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "Client Inc",
            "company_id": 1
        }
    ],
    "message": "OK",
    "errors": null
}

Create Client

POST

http://localhost:8000

/api/v1/clients

requires authentication

Create a new client.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Client name.

Example:

Client Inc

company_id

integer

required

Associated company ID.

Example:

client_code

string

required

External client code. Must not be greater than 255 characters.

Example:

sample

pc_client_id

string

required

Payroll company client identifier. Must not be greater than 255 characters.

Example:

sample

policy

string

Policy identifier or label. Must not be greater than 255 characters.

Example:

sample

fein

string

Federal Employer Identification Number. Must not be greater than 255 characters.

Example:

sample

effective_date

string

Effective date in YYYY-MM-DD format. Must be a valid date.

Example:

2026-04-02

location_code

string

Location code. Must not be greater than 255 characters.

Example:

sample

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/clients" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Client Inc\",
    \"company_id\": 1,
    \"client_code\": \"sample\",
    \"pc_client_id\": \"sample\",
    \"policy\": \"sample\",
    \"fein\": \"sample\",
    \"effective_date\": \"2026-04-02\",
    \"location_code\": \"sample\"
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "Client Inc",
        "company_id": 1
    },
    "message": "Created",
    "errors": null
}

Show Client

GET

http://localhost:8000

/api/v1/clients/{id}

requires authentication

Retrieve a specific client.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the client.

Example:

client

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/clients/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "Client Inc",
        "company_id": 1
    },
    "message": "OK",
    "errors": null
}

Update Client

PUT

PATCH

http://localhost:8000

/api/v1/clients/{id}

requires authentication

Update an existing client.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the client.

Example:

client

integer

required

Example:

Body Parameters

name

string

Client name.

Example:

Client Inc

company_id

integer

Associated company ID.

Example:

client_code

string

External client code. Must not be greater than 255 characters.

Example:

sample

pc_client_id

string

Payroll company client identifier. Must not be greater than 255 characters.

Example:

sample

policy

string

Policy identifier or label. Must not be greater than 255 characters.

Example:

sample

fein

string

Federal Employer Identification Number. Must not be greater than 255 characters.

Example:

sample

effective_date

string

Effective date in YYYY-MM-DD format. Must be a valid date.

Example:

2026-04-02

location_code

string

Location code. Must not be greater than 255 characters.

Example:

sample

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/clients/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Client Inc\",
    \"company_id\": 1,
    \"client_code\": \"sample\",
    \"pc_client_id\": \"sample\",
    \"policy\": \"sample\",
    \"fein\": \"sample\",
    \"effective_date\": \"2026-04-02\",
    \"location_code\": \"sample\"
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Client Inc",
        "company_id": 1
    },
    "message": "OK",
    "errors": null
}

Delete Client

DELETE

http://localhost:8000

/api/v1/clients/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the client.

Example:

client

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/clients/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a client.

Companies

APIs for managing company resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/companies/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/companies/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Companies

GET

http://localhost:8000

/api/v1/companies

requires authentication

Retrieve a paginated list of companies.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/companies?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "Acme Corp"
        }
    ],
    "message": "OK",
    "errors": null
}

Create Company

POST

http://localhost:8000

/api/v1/companies

requires authentication

Create a new company.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Company name.

Example:

Acme Corp

logo

string

Logo.

Example:

sample

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/companies" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Acme Corp\",
    \"logo\": \"sample\"
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "Acme Corp"
    },
    "message": "Created",
    "errors": null
}

Show Company

GET

http://localhost:8000

/api/v1/companies/{id}

requires authentication

Retrieve a specific company.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company.

Example:

company

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/companies/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "Acme Corp"
    },
    "message": "OK",
    "errors": null
}

Update Company

PUT

PATCH

http://localhost:8000

/api/v1/companies/{id}

requires authentication

Update an existing company.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company.

Example:

company

integer

required

Example:

Body Parameters

name

string

Company name.

Example:

Acme Corp

logo

string

Logo.

Example:

sample

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/companies/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Acme Corp\",
    \"logo\": \"sample\"
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Acme Corp"
    },
    "message": "OK",
    "errors": null
}

Delete Company

DELETE

http://localhost:8000

/api/v1/companies/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company.

Example:

company

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/companies/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a company.

Company Mappings

APIs for managing company mapping configurations with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/company-mappings/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/company-mappings/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Company Mappings

GET

http://localhost:8000

/api/v1/company-mappings

requires authentication

Retrieve a paginated list of company mappings.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/company-mappings?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "Default Mapping",
            "company_id": 1,
            "carrier_id": 1,
            "mode": "MAPPING"
        }
    ],
    "message": "OK",
    "errors": null
}

Create Company Mapping

POST

http://localhost:8000

/api/v1/company-mappings

requires authentication

Create a new company mapping.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Mapping name.

Example:

Default Mapping

company_id

integer

required

Associated company ID.

Example:

carrier_id

integer

Carrier ID.

Example:

header_row

integer

Header row number.

Example:

mapping

object

required

Column mapping data.

version

string

Version string.

Example:

1.0

active

boolean

Whether mapping is active.

Example:

true

mode

string

required

Mode type.

Example:

MAPPING

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/company-mappings" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Default Mapping\",
    \"company_id\": 1,
    \"carrier_id\": 1,
    \"header_row\": 1,
    \"mapping\": null,
    \"version\": \"1.0\",
    \"active\": true,
    \"mode\": \"MAPPING\"
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "Default Mapping",
        "company_id": 1,
        "carrier_id": 1,
        "mode": "MAPPING"
    },
    "message": "Created",
    "errors": null
}

Show Company Mapping

GET

http://localhost:8000

/api/v1/company-mappings/{id}

requires authentication

Retrieve a specific company mapping.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company mapping.

Example:

company_mapping

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/company-mappings/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "Default Mapping",
        "company_id": 1,
        "carrier_id": 1,
        "mode": "MAPPING"
    },
    "message": "OK",
    "errors": null
}

Update Company Mapping

PUT

PATCH

http://localhost:8000

/api/v1/company-mappings/{id}

requires authentication

Update an existing company mapping.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company mapping.

Example:

company_mapping

integer

required

Example:

Body Parameters

name

string

Mapping name.

Example:

Default Mapping

company_id

integer

Associated company ID.

Example:

carrier_id

integer

Carrier ID.

Example:

header_row

integer

Header row number.

Example:

mapping

object

Column mapping data.

version

string

Version string.

Example:

1.0

active

boolean

Whether mapping is active.

Example:

true

mode

string

Mode type.

Example:

MAPPING

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/company-mappings/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Default Mapping\",
    \"company_id\": 1,
    \"carrier_id\": 1,
    \"header_row\": 1,
    \"version\": \"1.0\",
    \"active\": true,
    \"mode\": \"MAPPING\"
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Default Mapping",
        "company_id": 1,
        "carrier_id": 1,
        "mode": "MAPPING"
    },
    "message": "OK",
    "errors": null
}

Delete Company Mapping

DELETE

http://localhost:8000

/api/v1/company-mappings/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the company mapping.

Example:

company_mapping

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/company-mappings/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a company mapping.

Drivers

APIs for managing driver resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/drivers/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/drivers/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Drivers

GET

http://localhost:8000

/api/v1/drivers

requires authentication

Retrieve a paginated list of drivers.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/drivers?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "CSV Parser",
            "single_record": false,
            "is_active": true
        }
    ],
    "message": "OK",
    "errors": null
}

Create Driver

POST

http://localhost:8000

/api/v1/drivers

requires authentication

Create a new driver.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Driver name.

Example:

CSV Parser

single_record

boolean

Whether the driver processes a single record.

Example:

false

is_active

boolean

Whether the driver is active.

Example:

true

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/drivers" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"CSV Parser\",
    \"single_record\": false,
    \"is_active\": true
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "CSV Parser",
        "single_record": false,
        "is_active": true
    },
    "message": "Created",
    "errors": null
}

Show Driver

GET

http://localhost:8000

/api/v1/drivers/{id}

requires authentication

Retrieve a specific driver.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the driver.

Example:

driver

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/drivers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "CSV Parser",
        "single_record": false,
        "is_active": true
    },
    "message": "OK",
    "errors": null
}

Update Driver

PUT

PATCH

http://localhost:8000

/api/v1/drivers/{id}

requires authentication

Update an existing driver.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the driver.

Example:

driver

integer

required

Example:

Body Parameters

name

string

Driver name.

Example:

CSV Parser Updated

single_record

boolean

Whether the driver processes a single record.

Example:

false

is_active

boolean

Whether the driver is active.

Example:

true

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/drivers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"CSV Parser Updated\",
    \"single_record\": false,
    \"is_active\": true
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "CSV Parser Updated",
        "single_record": false,
        "is_active": true
    },
    "message": "OK",
    "errors": null
}

Delete Driver

DELETE

http://localhost:8000

/api/v1/drivers/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the driver.

Example:

driver

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/drivers/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a driver.

Extractors

APIs for managing extractor resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/extractors/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/extractors/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Extractors

GET

http://localhost:8000

/api/v1/extractors

requires authentication

Retrieve a paginated list of extractors.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/extractors?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "Default Extractor",
            "class": "App\\Extractors\\DefaultExtractor",
            "company_id": 1,
            "carrier_id": 1
        }
    ],
    "message": "OK",
    "errors": null
}

Create Extractor

POST

http://localhost:8000

/api/v1/extractors

requires authentication

Create a new extractor.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Extractor name.

Example:

Default Extractor

class

string

required

Extractor class path.

Example:

App\\Extractors\\DefaultExtractor

company_id

integer

required

Associated company ID.

Example:

carrier_id

integer

Associated carrier ID.

Example:

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/extractors" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Default Extractor\",
    \"class\": \"App\\\\\\\\Extractors\\\\\\\\DefaultExtractor\",
    \"company_id\": 1,
    \"carrier_id\": 1
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "Default Extractor",
        "class": "App\\Extractors\\DefaultExtractor",
        "company_id": 1,
        "carrier_id": 1
    },
    "message": "Created",
    "errors": null
}

Show Extractor

GET

http://localhost:8000

/api/v1/extractors/{id}

requires authentication

Retrieve a specific extractor.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the extractor.

Example:

extractor

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/extractors/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "Default Extractor",
        "class": "App\\Extractors\\DefaultExtractor",
        "company_id": 1,
        "carrier_id": 1
    },
    "message": "OK",
    "errors": null
}

Update Extractor

PUT

PATCH

http://localhost:8000

/api/v1/extractors/{id}

requires authentication

Update an existing extractor.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the extractor.

Example:

extractor

integer

required

Example:

Body Parameters

name

string

Extractor name.

Example:

Updated Extractor

class

string

Extractor class path.

Example:

App\\Extractors\\UpdatedExtractor

company_id

integer

Associated company ID.

Example:

carrier_id

integer

Associated carrier ID.

Example:

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/extractors/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Updated Extractor\",
    \"class\": \"App\\\\\\\\Extractors\\\\\\\\UpdatedExtractor\",
    \"company_id\": 1,
    \"carrier_id\": 1
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Updated Extractor",
        "class": "App\\Extractors\\UpdatedExtractor",
        "company_id": 1,
        "carrier_id": 1
    },
    "message": "OK",
    "errors": null
}

Delete Extractor

DELETE

http://localhost:8000

/api/v1/extractors/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the extractor.

Example:

extractor

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/extractors/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete an extractor.

Files

APIs for managing file resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/files/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/files/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

Download File

GET

http://localhost:8000

/api/v1/files/download/{file_id}

requires authentication

Download a file's decompressed binary content.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

file_id

integer

required

The ID of the file.

Example:

file

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/files/download/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "Binary file stream returned."
}

List Files

GET

http://localhost:8000

/api/v1/files

requires authentication

Retrieve a paginated list of files.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/files?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "document.txt"
        }
    ],
    "message": "OK",
    "errors": null
}

Create File

POST

http://localhost:8000

/api/v1/files

requires authentication

Create a new file record.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

File name.

Example:

document.txt

content

string

required

File content.

Example:

This is file content

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/files" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"document.txt\",
    \"content\": \"This is file content\"
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "document.txt"
    },
    "message": "Created",
    "errors": null
}

Show File

GET

http://localhost:8000

/api/v1/files/{id}

requires authentication

Retrieve a specific file record.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the file.

Example:

file

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/files/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "document.txt"
    },
    "message": "OK",
    "errors": null
}

Update File

PUT

PATCH

http://localhost:8000

/api/v1/files/{id}

requires authentication

Update an existing file record.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the file.

Example:

file

integer

required

Example:

Body Parameters

name

string

File name.

Example:

updated_document.txt

content

string

File content.

Example:

Updated content

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/files/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"updated_document.txt\",
    \"content\": \"Updated content\"
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "updated_document.txt"
    },
    "message": "OK",
    "errors": null
}

Delete File

DELETE

http://localhost:8000

/api/v1/files/{id}

requires authentication

Delete a file record.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the file.

Example:

file

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/files/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": null,
    "message": "Deleted",
    "errors": null
}

Formatters

APIs for managing formatter resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/formatters/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/formatters/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Formatters

GET

http://localhost:8000

/api/v1/formatters

requires authentication

Retrieve a paginated list of formatters.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/formatters?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "Default Formatter",
            "class": "App\\Formatters\\DefaultFormatter",
            "carrier_id": 1
        }
    ],
    "message": "OK",
    "errors": null
}

Create Formatter

POST

http://localhost:8000

/api/v1/formatters

requires authentication

Create a new formatter.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Formatter name.

Example:

Default Formatter

class

string

required

Formatter class path.

Example:

App\\Formatters\\DefaultFormatter

carrier_id

integer

required

Associated carrier ID.

Example:

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/formatters" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Default Formatter\",
    \"class\": \"App\\\\\\\\Formatters\\\\\\\\DefaultFormatter\",
    \"carrier_id\": 1
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "Default Formatter",
        "class": "App\\Formatters\\DefaultFormatter",
        "carrier_id": 1
    },
    "message": "Created",
    "errors": null
}

Show Formatter

GET

http://localhost:8000

/api/v1/formatters/{id}

requires authentication

Retrieve a specific formatter.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the formatter.

Example:

formatter

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/formatters/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "Default Formatter",
        "class": "App\\Formatters\\DefaultFormatter",
        "carrier_id": 1
    },
    "message": "OK",
    "errors": null
}

Update Formatter

PUT

PATCH

http://localhost:8000

/api/v1/formatters/{id}

requires authentication

Update an existing formatter.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the formatter.

Example:

formatter

integer

required

Example:

Body Parameters

name

string

Formatter name.

Example:

Updated Formatter

class

string

Formatter class path.

Example:

App\\Formatters\\UpdatedFormatter

carrier_id

integer

Associated carrier ID.

Example:

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/formatters/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Updated Formatter\",
    \"class\": \"App\\\\\\\\Formatters\\\\\\\\UpdatedFormatter\",
    \"carrier_id\": 1
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Updated Formatter",
        "class": "App\\Formatters\\UpdatedFormatter",
        "carrier_id": 1
    },
    "message": "OK",
    "errors": null
}

Delete Formatter

DELETE

http://localhost:8000

/api/v1/formatters/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the formatter.

Example:

formatter

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/formatters/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a formatter.

Imports

APIs for managing import resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/imports/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/imports/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

Validate Import File

POST

http://localhost:8000

/api/v1/imports/validate

requires authentication

Detect matching extractor and return available mappings for the uploaded file.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

data_file

file

required

Source file to validate. Supported: csv, txt, xls, xlsx, pdf.

Example:

/tmp/phpkaqtkmcct82m48lWLuT

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/imports/validate" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "data_file=@/tmp/phpkaqtkmcct82m48lWLuT"

Example response:

{
    "data": {
        "status": "success",
        "message": "File validated successfully",
        "extractor": "Asure",
        "data": "Employee ID,Name\n\"1001\",\"Jane Doe\"\n",
        "mappings": [
            {
                "id": 1,
                "name": "Asure Mapping",
                "company_name": "Acme Payroll",
                "carrier_name": "Guardian"
            }
        ]
    },
    "message": "File validated",
    "errors": null
}

Preview Import Data

POST

http://localhost:8000

/api/v1/imports/preview

requires authentication

Run mapping or extraction + formatting pipeline and return preview data.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

mapping_id

integer

required

Mapping to run for preview.

Example:

data_file

file

required

Source file to preview. Supported: csv, txt, xls, xlsx, pdf.

Example:

/tmp/phpup6g546ep2700WNVMqQ

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/imports/preview" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "mapping_id=1"\
    --form "data_file=@/tmp/phpup6g546ep2700WNVMqQ"

Example response:

{
    "data": {
        "status": "success",
        "mode": "MAPPING",
        "data": "formatted-preview-content"
    },
    "message": "Preview generated",
    "errors": null
}

Submit Import

POST

http://localhost:8000

/api/v1/imports/submit

requires authentication

Run full import pipeline and submit data to the carrier destination.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

mapping_id

integer

required

Mapping to run for import submission.

Example:

data_file

file

required

Source file to process and submit. Supported: csv, txt, xls, xlsx, pdf.

Example:

/tmp/phpvve96paaurnna6yDVF5

payroll_company_id

integer

Optional payroll company override.

Example:

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/imports/submit" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "mapping_id=1"\
    --form "payroll_company_id=2"\
    --form "data_file=@/tmp/phpvve96paaurnna6yDVF5"

Example response:

{
    "data": {
        "message": "Data was sent to carrier successfully.",
        "carrier_id": 5
    },
    "message": "Import submitted",
    "errors": null
}

List Imports

GET

http://localhost:8000

/api/v1/imports

requires authentication

Retrieve a paginated list of imports.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/imports?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "user_id": 1,
            "carrier_id": 1,
            "file_id": 1
        }
    ],
    "message": "OK",
    "errors": null
}

Create Import

POST

http://localhost:8000

/api/v1/imports

requires authentication

Create a new import.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

user_id

integer

required

Associated user ID.

Example:

payroll_company_id

integer

required

Associated payroll company ID.

Example:

carrier_id

integer

required

Associated carrier ID.

Example:

file_id

integer

required

Associated file ID.

Example:

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/imports" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": 1,
    \"payroll_company_id\": 1,
    \"carrier_id\": 1,
    \"file_id\": 1
}"

Example response:

{
    "data": {
        "id": 2,
        "user_id": 1,
        "carrier_id": 1,
        "file_id": 1
    },
    "message": "Created",
    "errors": null
}

Show Import

GET

http://localhost:8000

/api/v1/imports/{id}

requires authentication

Retrieve a specific import.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the import.

Example:

import

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/imports/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "user_id": 1,
        "carrier_id": 1,
        "file_id": 1
    },
    "message": "OK",
    "errors": null
}

Update Import

PUT

PATCH

http://localhost:8000

/api/v1/imports/{id}

requires authentication

Update an existing import.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the import.

Example:

import

integer

required

Example:

Body Parameters

user_id

integer

Associated user ID.

Example:

payroll_company_id

integer

Associated payroll company ID.

Example:

carrier_id

integer

Associated carrier ID.

Example:

file_id

integer

Associated file ID.

Example:

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/imports/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": 1,
    \"payroll_company_id\": 1,
    \"carrier_id\": 1,
    \"file_id\": 1
}"

Example response:

{
    "data": {
        "id": 1,
        "user_id": 1,
        "carrier_id": 1,
        "file_id": 1
    },
    "message": "OK",
    "errors": null
}

Delete Import

DELETE

http://localhost:8000

/api/v1/imports/{id}

requires authentication

Delete an import.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the import.

Example:

import

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/imports/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": null,
    "message": "Deleted",
    "errors": null
}

Permissions

APIs for managing application permissions.

Count Records

GET

http://localhost:8000

/api/v1/permissions/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/permissions/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Permissions

GET

http://localhost:8000

/api/v1/permissions

requires authentication

Retrieve all permissions.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/permissions" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "create reports"
        }
    ],
    "message": "OK",
    "errors": null
}

Create Permission

POST

http://localhost:8000

/api/v1/permissions

requires authentication

Create a new permission.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Permission name.

Example:

create reports

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/permissions" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"create reports\"
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "create reports"
    },
    "message": "Created",
    "errors": null
}

Delete Permission

DELETE

http://localhost:8000

/api/v1/permissions/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the permission.

Example:

permission

integer

required

Permission ID.

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/permissions/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete an existing permission.

Profile

APIs for managing the authenticated user's own profile.

Show Profile

GET

http://localhost:8000

/api/v1/profile

requires authentication

Retrieve the authenticated user's profile.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/profile" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "user": {
            "id": 1,
            "name": "Profile Tester",
            "email": "profile@example.com",
            "roles": [
                "user"
            ]
        },
        "email_verified_at": "2026-04-15T09:00:00.000000Z"
    },
    "message": "OK",
    "errors": null
}

Update Profile

PATCH

http://localhost:8000

/api/v1/profile

requires authentication

Update the authenticated user's profile information.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Full name.

Example:

Jane Doe

string

required

Unique email address.

Example:

jane.doe@example.com

Example request:

curl --request PATCH \
    "http://localhost:8000/api/v1/profile" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Jane Doe\",
    \"email\": \"jane.doe@example.com\"
}"

Example response:

{
    "data": {
        "user": {
            "id": 1,
            "name": "Jane Doe",
            "email": "jane.doe@example.com",
            "roles": [
                "user"
            ]
        },
        "email_verified_at": null
    },
    "message": "Profile updated",
    "errors": null
}

Update Profile Password

PUT

http://localhost:8000

/api/v1/profile/password

requires authentication

Update the authenticated user's password.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

current_password

string

required

Current account password.

Example:

password123

password

string

required

New password.

Example:

NewStrongPassword123!

password_confirmation

string

required

Password confirmation.

Example:

NewStrongPassword123!

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/profile/password" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"current_password\": \"password123\",
    \"password\": \"NewStrongPassword123!\",
    \"password_confirmation\": \"NewStrongPassword123!\"
}"

Example response:

{
    "data": null,
    "message": "Password updated",
    "errors": null
}

Delete Profile

DELETE

http://localhost:8000

/api/v1/profile

requires authentication

Delete the authenticated user's account.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

password

string

required

Current account password.

Example:

password123

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/profile" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"password\": \"password123\"
}"

Example response:

{
    "data": null,
    "message": "Profile deleted",
    "errors": null
}

Roles

APIs for managing application roles with permissions.

Count Records

GET

http://localhost:8000

/api/v1/roles/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/roles/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Roles

GET

http://localhost:8000

/api/v1/roles

requires authentication

Retrieve all roles with permissions.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/roles" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "admin",
            "permissions": [
                {
                    "id": 1,
                    "name": "manage users"
                }
            ]
        }
    ],
    "message": "OK",
    "errors": null
}

Create Role

POST

http://localhost:8000

/api/v1/roles

requires authentication

Create a new role.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

Unique role name.

Example:

moderator

permissions

string[]

Permissions to assign.

Example:

[1,2,3]

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/roles" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"moderator\",
    \"permissions\": [
        1,
        2,
        3
    ]
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "moderator",
        "permissions": [
            {
                "id": 1,
                "name": "manage users"
            }
        ]
    },
    "message": "Created",
    "errors": null
}

Show Role

GET

http://localhost:8000

/api/v1/roles/{id}

requires authentication

Retrieve a specific role.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the role.

Example:

role

integer

required

Role ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/roles/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "admin",
        "permissions": [
            {
                "id": 1,
                "name": "manage users"
            }
        ]
    },
    "message": "OK",
    "errors": null
}

Update Role

PUT

PATCH

http://localhost:8000

/api/v1/roles/{id}

requires authentication

Update an existing role.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the role.

Example:

role

integer

required

Role ID.

Example:

Body Parameters

name

string

Role name.

Example:

moderator

permissions

string[]

Permissions to assign.

Example:

[1,2,3]

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/roles/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"moderator\",
    \"permissions\": [
        1,
        2,
        3
    ]
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "moderator",
        "permissions": [
            {
                "id": 1,
                "name": "manage users"
            }
        ]
    },
    "message": "OK",
    "errors": null
}

Delete Role

DELETE

http://localhost:8000

/api/v1/roles/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the role.

Example:

role

integer

required

Role ID.

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/roles/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a role.

Submissions

APIs for managing submission resources with role-based authorization.

Count Records

GET

http://localhost:8000

/api/v1/submissions/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/submissions/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Submissions

GET

http://localhost:8000

/api/v1/submissions

requires authentication

Retrieve a paginated list of submissions.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Example:

per_page

integer

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/submissions?page=1&per_page=15" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "carrier_id": 1,
            "status": "submitted"
        }
    ],
    "message": "OK",
    "errors": null
}

Create Submission

POST

http://localhost:8000

/api/v1/submissions

requires authentication

Create a new submission.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

carrier_id

integer

Optional carrier ID used for submission routing. The id of an existing record in the carriers table.

Example:

import_id

integer

Optional import record ID this submission came from. The id of an existing record in the imports table.

Example:

data

object

required

Submission payload sent to the downstream carrier endpoint.

Example:

{"batch":"20260402","records":125,"source":"payroll-sync"}

status

string

required

Submission status code. Allowed values: 0 (pending), 1 (sent), 2 (failed).

Must be one of:

Example:

sent_by

integer

required

User ID of the actor/system creating this submission. The id of an existing record in the users table.

Example:

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/submissions" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"carrier_id\": 1,
    \"import_id\": 10,
    \"data\": {
        \"batch\": \"20260402\",
        \"records\": 125,
        \"source\": \"payroll-sync\"
    },
    \"status\": \"0\",
    \"sent_by\": 1
}"

Example response:

{
    "data": {
        "id": 2,
        "carrier_id": 1,
        "status": "queued"
    },
    "message": "Created",
    "errors": null
}

Show Submission

GET

http://localhost:8000

/api/v1/submissions/{id}

requires authentication

Retrieve a specific submission.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the submission.

Example:

submission

integer

required

Submission ID.

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/submissions/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "carrier_id": 1,
        "user_sent_by": {
            "id": 1,
            "name": "John Doe"
        },
        "status": "submitted"
    },
    "message": "OK",
    "errors": null
}

Update Submission

PUT

PATCH

http://localhost:8000

/api/v1/submissions/{id}

requires authentication

Update an existing submission.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the submission.

Example:

submission

integer

required

Submission ID.

Example:

Body Parameters

carrier_id

integer

Updated carrier ID for routing or reassignment. The id of an existing record in the carriers table.

Example:

import_id

integer

Updated related import ID. The id of an existing record in the imports table.

Example:

data

object

Updated submission payload.

Example:

{"batch":"20260403","records":132,"source":"manual-retry"}

status

string

Updated status code. Allowed values: 0 (pending), 1 (sent), 2 (failed).

Must be one of:

Example:

sent_by

integer

Updated sender user ID. The id of an existing record in the users table.

Example:

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/submissions/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"carrier_id\": 2,
    \"import_id\": 11,
    \"data\": {
        \"batch\": \"20260403\",
        \"records\": 132,
        \"source\": \"manual-retry\"
    },
    \"status\": \"1\",
    \"sent_by\": 2
}"

Example response:

{
    "data": {
        "id": 1,
        "carrier_id": 1,
        "status": "submitted"
    },
    "message": "OK",
    "errors": null
}

Delete Submission

DELETE

http://localhost:8000

/api/v1/submissions/{id}

requires authentication

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the submission.

Example:

submission

integer

required

Submission ID.

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/submissions/16" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{"data":null,"message":"Deleted","errors":null}
Delete a submission.

Users

APIs for managing application users with role assignment.

Count Records

GET

http://localhost:8000

/api/v1/users/count

requires authentication

Return the total number of records for this resource.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/users/count" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "count": 42
    },
    "message": "OK",
    "errors": null
}

List Users

GET

http://localhost:8000

/api/v1/users

requires authentication

Retrieve all users.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/users" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        }
    ],
    "message": "OK",
    "errors": null
}

Create User

POST

http://localhost:8000

/api/v1/users

requires authentication

Create a new user.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

User full name.

Example:

John Doe

string

required

Unique email address.

Example:

john@example.com

password

string

required

Minimum 6 characters.

Example:

password123

roles

string[]

Role IDs to assign.

Example:

[1,2]

Example request:

curl --request POST \
    "http://localhost:8000/api/v1/users" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"John Doe\",
    \"email\": \"john@example.com\",
    \"password\": \"password123\",
    \"roles\": [
        1,
        2
    ]
}"

Example response:

{
    "data": {
        "id": 2,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "message": "Created",
    "errors": null
}

Show User

GET

http://localhost:8000

/api/v1/users/{id}

requires authentication

Retrieve a specific user.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the user.

Example:

user

integer

required

Example:

Example request:

curl --request GET \
    --get "http://localhost:8000/api/v1/users/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "message": "OK",
    "errors": null
}

Update User

PUT

PATCH

http://localhost:8000

/api/v1/users/{id}

requires authentication

Update an existing user.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the user.

Example:

user

integer

required

Example:

Body Parameters

name

string

User full name.

Example:

Jane Doe

string

Unique email address.

Example:

jane@example.com

password

string

Minimum 6 characters.

Example:

newpassword123

roles

string[]

Role IDs to assign.

Example:

[1,2]

Example request:

curl --request PUT \
    "http://localhost:8000/api/v1/users/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Jane Doe\",
    \"email\": \"jane@example.com\",
    \"password\": \"newpassword123\",
    \"roles\": [
        1,
        2
    ]
}"

Example response:

{
    "data": {
        "id": 1,
        "name": "Jane Doe",
        "email": "jane@example.com"
    },
    "message": "OK",
    "errors": null
}

Delete User

DELETE

http://localhost:8000

/api/v1/users/{id}

requires authentication

Delete a user.

Headers

Authorization

Example:

{YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

required

The ID of the user.

Example:

user

integer

required

Example:

Example request:

curl --request DELETE \
    "http://localhost:8000/api/v1/users/1" \
    --header "Authorization: {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": null,
    "message": "Deleted",
    "errors": null
}

PayComp API

Introduction

API Stats

Who this is for

What you can build

How to use this guide

Security

Quickstart Demo

Password Reset Flow

Authenticating requests

Authentication

User Login

Headers

Body Parameters

Forgot Password

Headers

Body Parameters

Reset Password

Headers

Body Parameters

Refresh JWT Token

Headers

User Logout

Headers

Carriers

Count Records

Headers

Resolve Carrier Submission Form Metadata

Headers

URL Parameters

Submit Carrier Test File

Headers

URL Parameters

Body Parameters

Get Carrier Formatter Fields

Headers

URL Parameters

List Carrier SFTP Remote Files

Headers

URL Parameters

Download Carrier SFTP Remote File

Headers

URL Parameters

Build Carrier SFTP GPG Preview

Headers

URL Parameters

Body Parameters

List Carriers

Headers

Query Parameters

Create Carrier

Headers

Body Parameters

Show Carrier

Headers

URL Parameters

Update Carrier

Headers

URL Parameters

Body Parameters

Delete Carrier

Headers

URL Parameters

Clients

Count Records

Headers

List Clients

Headers

Query Parameters

Create Client

Headers

Body Parameters

Show Client

Headers

URL Parameters

Update Client

Headers

URL Parameters

Body Parameters

Delete Client