openapi: 3.2.0
info:
title: 1Fort API Documentation Broker API
description: '# 1Fort API
REST API for the 1Fort insurance platform. This document is the authoritative
map of the API surface; endpoints are grouped in the sidebar by **app** and
**version**, and large apps are split into per-resource sub-groups.
## Authentication
Almost every endpoint requires a **JWT access token**. Send it in the
`Authorization` header as either `Bearer <token>` or `JWT <token>`. Tokens may
also be presented as an HTTP-only cookie. Endpoints documented with no security
requirement are intentionally public (for example sign-in, OTP and storefront
endpoints).
## Multi-tenancy
Resources are scoped to a tenant. Nested routes carry the owning resource id in
the path (for example `/v2/broker/{business_pk}/applications`); a token is only
authorised for the businesses its user may access. Object-level permissions are
enforced per endpoint.
## Versioning
`v2` endpoints live under `/apis/v2/...` and are the current surface. `v1`
endpoints remain documented for compatibility. Endpoints marked **deprecated**
are scheduled for removal; prefer the documented replacement.
'
termsOfService: https://www.1fort.com/
license:
name: Privately owned
version: v1
servers:
- url: https://api.1fort.com/apis/
security:
- Bearer: []
tags:
- name: broker
x-displayName: Broker
description: '**Access:** mixed; some endpoints are public, others require JWT (per endpoint).'
paths:
/broker:
parameters: []
get:
operationId: broker_list
summary: List Brokers
description: '
List all brokers.
This endpoint lists all brokers.
'
parameters:
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerAgency'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
post:
operationId: broker_create
summary: Create Broker
description: '
Create a broker.
This endpoint creates a broker.
'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerAgency'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerAgency'
required: true
/broker/{broker_pk}/accept-invite:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
post:
operationId: broker_accept-invite_create
summary: Accept Invite
description: '
Accept an invite.
This endpoint accepts a broker user(agent) invite.
'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptBrokerInvite'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
security: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptBrokerInvite'
required: true
/broker/{broker_pk}/clients:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_clients_list
summary: List Broker Clients
description: '
List all clients.
This endpoint lists all the broker''s clients.
'
parameters:
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type:
- string
- 'null'
format: uri
previous:
type:
- string
- 'null'
format: uri
results:
type: array
items:
$ref: '#/components/schemas/BrokerClient'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
post:
operationId: broker_clients_create
summary: Create Broker Client
description: "\nCreate a broker client.\nThis endpoint creates a client.\n\nA subsidiaries list can be passed to create\na client with subsidiaries.\nExample:\n\"subsidiaries\": [\n {\n \"name\": \"Subsidiary 1\",\n }\n]\n"
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerClient'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerClient'
required: true
/broker/{broker_pk}/clients/{client_pk}/invites:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
- name: client_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_clients_invites_list
summary: List Broker Client Invites
description: '
List all client invites.
This endpoint lists all the broker''s client invites.
'
parameters:
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
post:
operationId: broker_clients_invites_create
summary: Invite Client
description: '
Send an invite to a client.
This endpoint creates a client invite.
Optional fields:
- application_id: Link invite to specific application
- trigger_email: Whether to send invitation email immediately
- custom_message: Personalized message to include in invitation email
'
responses:
'201':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerBusinessUserInvite'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerBusinessUserInvite'
required: true
/broker/{broker_pk}/clients/{client_pk}/invites/cancel-invite:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
- name: client_pk
in: path
required: true
schema:
type: string
post:
operationId: broker_clients_invites_cancel_invite
summary: Cancel Broker Client Invite
description: '
Cancel an invite to a client.
This endpoint deletes all broker client invites.
'
responses:
'201':
description: ''
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/clients/{client_pk}/invites/resend-invite:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
- name: client_pk
in: path
required: true
schema:
type: string
post:
operationId: broker_clients_invites_resend_invite
summary: Resend Broker Client Invite
description: '
Resend an invite to a client.
This endpoint resends an existing pending client invite.
'
responses:
'201':
description: ''
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/clients/{id}:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
- name: id
in: path
description: A unique integer value identifying this business.
required: true
schema:
type: integer
get:
operationId: broker_clients_read
summary: Get Broker Client details
description: '
Retrieve a broker client.
This endpoint Get a broker client.
'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerClient'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
patch:
operationId: broker_clients_partial_update
summary: Update Broker Client
description: '
Update a broker client.
This endpoint updates a broker client.
'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerClient'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerClient'
required: true
delete:
operationId: broker_clients_delete
summary: Delete Broker Client
description: '
Delete a broker client.
This endpoint deletes a broker client.
'
responses:
'204':
description: ''
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/files:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_files_list
summary: List Broker Files
description: '
List all files associated with the broker''s insureds.
This endpoint aggregates files from multiple sources:
- Quote files (Herald quotes, manual quotes)
- Application supplementary documents
- Policy documents
- Carrier files (invoices, etc.)
**Query Parameters:**
- `search` (optional): Search by file name
- `file_type` (optional): Filter by file type (cois, quote, proposal, application, policy, invoice)
- `insured` (optional): Filter by insured ID (comma-separated for multiple)
- `team` (optional): Filter by team member ID (comma-separated for multiple)
- `date_min` (optional): Filter by minimum date (YYYY-MM-DD, compared in UTC)
- `date_max` (optional): Filter by maximum date (YYYY-MM-DD, compared in UTC)
- `source` (optional): Filter by source (email, platform)
- `limit` (optional): Number of results per page (default: 10)
- `offset` (optional): Starting position for pagination (default: 0)
**Authorization:**
Returns 403 Forbidden if the authenticated user doesn''t belong to the specified broker agency.
'
parameters:
- name: search
in: query
description: Search files by name
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: 'Number of results per page (default: 10)'
schema:
type: integer
- name: offset
in: query
description: 'Starting position for pagination (default: 0)'
schema:
type: integer
- name: file_type
in: query
description: Filter by file type (comma-separated)
schema:
type: string
- name: insured
in: query
description: Filter by insured ID (comma-separated)
schema:
type: string
- name: team
in: query
description: Filter by team member ID (comma-separated)
schema:
type: string
- name: date_min
in: query
description: Filter by minimum date (YYYY-MM-DD, compared in UTC)
schema:
type: string
format: date
- name: date_max
in: query
description: Filter by maximum date (YYYY-MM-DD, compared in UTC)
schema:
type: string
format: date
- name: source
in: query
description: Filter by source (email, platform)
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerFile'
'403':
description: User does not have access to this broker
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/invites:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_invites_list
summary: List Broker User Invites
description: '
List all user invites.
This endpoint lists all the broker''s user invites.
'
parameters:
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type:
- string
- 'null'
format: uri
previous:
type:
- string
- 'null'
format: uri
results:
type: array
items:
$ref: '#/components/schemas/BrokerUserInvite'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
post:
operationId: broker_invites_create
summary: Invite Broker User
description: '
Send an invite to an broker user(agent).
This endpoint invites a user.
'
responses:
'201':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerUserInvite'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerUserInvite'
required: true
/broker/{broker_pk}/invites/{id}:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
- name: id
in: path
description: A unique integer value identifying this broker invite.
required: true
schema:
type: integer
put:
operationId: broker_invites_update
summary: Update Broker User Invite
description: '
Update a pending broker user invite.
This endpoint allows updating the role and type of a pending invite.
Only pending invites can be updated.
'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerUserInvite'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerUserInvite'
required: true
patch:
operationId: broker_invites_partial_update
summary: Partially Update Broker User Invite
description: '
Partially update a pending broker user invite.
This endpoint allows updating the role and/or type of a pending invite.
Only pending invites can be updated.
'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerUserInvite'
'400':
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrokerUserInvite'
required: true
delete:
operationId: broker_invites_delete
summary: Delete Broker User Invite
description: '
Delete a broker user invite.
This endpoint cancels a broker user invite by setting its status to cancelled.
'
responses:
'204':
description: ''
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'404':
description: Object does not exist or caller has insufficient permissions to access it.
content:
application/json:
schema:
$ref: '#/components/schemas/APIException'
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/notification-emails:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_notification-emails_list
summary: List Sent Notification Emails
description: '
List all successfully sent notification emails to business users and underwriters
associated with the authenticated broker''s agency.
Returns only emails with ''sent'' status.
Includes subject, sender, recipient, recipient type, and date sent information.
Only returns emails for businesses and underwriters belonging to the broker''s agency.
**Query Parameters:**
- `business_id` (optional): Filter emails to only show those sent to users of a specific business/insured
**Exclusions:**
- OTP/Login code emails are excluded from results
**Response Fields:**
- `id`: Unique identifier for the email
- `subject`: Email subject line
- `sender_email`: Sender''s email address
- `sender_name`: Sender''s display name
- `recipient_email`: Recipient''s email address
- `recipient_type`: Type of recipient - "Insured" (business user), "Carrier" (underwriter), or null
- `sent_at`: Timestamp when email was sent
- `created_at`: Timestamp when email was created
- `status`: Email status (always "sent" for this endpoint)
- `email_type`: Type of notification email (e.g., "BROKER_INACTIVITY", "BROKER_WEEKLY_DIGEST")
'
parameters:
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerNotificationEmail'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
tags:
- broker
/broker/{broker_pk}/received-notification-emails:
parameters:
- name: broker_pk
in: path
required: true
schema:
type: string
get:
operationId: broker_received-notification-emails_list
summary: List Received Notification Emails
description: '
List all successfully sent notification emails received by the authenticated broker user.
Returns only emails with ''sent'' status sent to the authenticated user making the request.
Includes subject, sender, recipient, and date sent information.
**Exclusions:**
- OTP/Login code emails are excluded from results
**Response Fields:**
- `id`: Unique identifier for the email
- `subject`: Email subject line
- `sender_email`: Sender''s email address
- `sender_name`: Sender''s display name
- `recipient_email`: Recipient''s email address (will match authenticated user''s email)
- `sent_at`: Timestamp when email was sent
- `created_at`: Timestamp when email was created
- `status`: Email status (always "sent" for this endpoint)
- `email_type`: Type of notification email (e.g., "BROKER_INACTIVITY", "BROKER_WEEKLY_DIGEST")
- `is_read`: Boolean indicating if the notification has been read (false for new emails on first GET)
**Note:** UserNotification records are auto-created on first GET request with "unread" status.
'
parameters:
- name: search
in: query
description: A search term.
required: false
schema:
type: string
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrokerReceivedNotificationEmail'
'403':
description: Authentication credentials were invalid, absent or insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'500':
description: Internal server error.
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/1fort/refs/heads/main/openapi/1fort-broker-api-openapi.yml