mirror of
https://github.com/GSA/notifications-api.git
synced 2025-12-08 14:12:27 -05:00
625 lines
16 KiB
YAML
625 lines
16 KiB
YAML
openapi: '3.0.2'
|
|
info:
|
|
title: Notify API
|
|
version: '1.0'
|
|
description: |
|
|
The following OpenAPI document lists a subset of the available APIs for US Notify.
|
|
|
|
We are currently API compatible with GOV.UK Notify. Please visit [their documentation](https://docs.notifications.service.gov.uk/rest-api.html)
|
|
for more information.
|
|
|
|
Authorization uses [a JSON Web Token (JWT) bearer token](https://docs.notifications.service.gov.uk/rest-api.html#authorisation-header). The internal-api
|
|
methods use the same scheme, but must use a specific key for the Admin UI.
|
|
servers:
|
|
- url: https://notify-api.app.cloud.gov
|
|
description: Production API endpoint
|
|
- url: https://notify-api-staging.app.cloud.gov
|
|
description: Staging API endpoint
|
|
- url: http://localhost:6011
|
|
description: Local development API endpoint
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
parameters:
|
|
uuidPath:
|
|
name: uuid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
schemas:
|
|
serviceObject:
|
|
type: object
|
|
properties:
|
|
active:
|
|
type: boolean
|
|
billing_contact_email_addresses:
|
|
type: string
|
|
billing_contact_names:
|
|
type: string
|
|
billing_reference:
|
|
type: string
|
|
consent_to_research:
|
|
type: string
|
|
contact_link:
|
|
type: string
|
|
count_as_live:
|
|
type: boolean
|
|
created_by:
|
|
type: string
|
|
email_branding:
|
|
type: string
|
|
email_from:
|
|
type: string
|
|
go_live_at:
|
|
type: string
|
|
go_live_user:
|
|
type: string
|
|
id:
|
|
type: string
|
|
inbound_api:
|
|
type: array
|
|
letter_branding:
|
|
type: string
|
|
message_limit:
|
|
type: number
|
|
name:
|
|
type: string
|
|
notes:
|
|
type: string
|
|
organization:
|
|
type: string
|
|
organization_type:
|
|
type: string
|
|
enum: ["federal", "state", "other"]
|
|
default: "federal"
|
|
permissions:
|
|
type: array
|
|
items:
|
|
type: string
|
|
prefix_sms:
|
|
type: boolean
|
|
purchase_order_number:
|
|
type: string
|
|
rate_limit:
|
|
type: number
|
|
research_model:
|
|
type: boolean
|
|
restricted:
|
|
type: boolean
|
|
service_callback_api:
|
|
type: array
|
|
volume_email:
|
|
type: string
|
|
volume_letter:
|
|
type: string
|
|
volume_sms:
|
|
type: string
|
|
userObject:
|
|
type: object
|
|
properties:
|
|
auth_type:
|
|
type: string
|
|
can_use_webauthn:
|
|
type: string
|
|
current_session_id:
|
|
type: string
|
|
email_access_validated_at:
|
|
type: string
|
|
email_address:
|
|
type: string
|
|
failed_login_count:
|
|
type: number
|
|
id:
|
|
type: string
|
|
logged_in_at:
|
|
type: string
|
|
mobile_number:
|
|
type: string
|
|
name:
|
|
type: string
|
|
organizations:
|
|
type: array
|
|
items:
|
|
type: string
|
|
password_changed_at:
|
|
type: string
|
|
permissions:
|
|
type: object
|
|
properties:
|
|
SERVICE_ID:
|
|
type: array
|
|
items:
|
|
type: string
|
|
platform_admin:
|
|
type: boolean
|
|
services:
|
|
type: array
|
|
items:
|
|
type: string
|
|
state:
|
|
type: string
|
|
enum: ["pending", "active", "inactive"]
|
|
apiKeyResponse:
|
|
type: object
|
|
properties:
|
|
apiKeys:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
created_by:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
expiry_date:
|
|
type: string
|
|
id:
|
|
type: string
|
|
key_type:
|
|
type: string
|
|
name:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
version:
|
|
type: number
|
|
templateObject:
|
|
type: object
|
|
properties:
|
|
body:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
id:
|
|
type: string
|
|
letter_contact_block:
|
|
type: object
|
|
name:
|
|
type: string
|
|
personalisation:
|
|
type: object
|
|
postage:
|
|
type: string
|
|
subject:
|
|
type: string
|
|
type:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
version:
|
|
type: integer
|
|
required:
|
|
- body
|
|
- created_at
|
|
- created_by
|
|
- id
|
|
- letter_contact_block
|
|
- name
|
|
- personalisation
|
|
- postage
|
|
- subject
|
|
- type
|
|
- updated_at
|
|
- version
|
|
additionalProperties: false
|
|
paths:
|
|
/_status?simple=1:
|
|
get:
|
|
description: 'Retrieve only an acknowledgement that the server is listening'
|
|
tags:
|
|
- public
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
/_status:
|
|
get:
|
|
description: 'Retrieve information on the status of the Notify API server'
|
|
tags:
|
|
- public
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
build_time:
|
|
type: string
|
|
db_version:
|
|
type: string
|
|
git_commit:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
/_status/live-service-and-organization-counts:
|
|
get:
|
|
description: 'Retrieve a count of live services and organizations in the Notify system'
|
|
tags:
|
|
- public
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
services:
|
|
type: number
|
|
organizations:
|
|
type: number
|
|
/user:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve list of all users'
|
|
tags:
|
|
- internal-api
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/userObject"
|
|
/user/{uuid}:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve single user details'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: "#/components/schemas/userObject"
|
|
/organizations:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve organization details'
|
|
tags:
|
|
- internal-api
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
active:
|
|
type: boolean
|
|
count_of_live_services:
|
|
type: number
|
|
domains:
|
|
type: array
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
organization_type:
|
|
type: string
|
|
enum: ["federal", "state", "other"]
|
|
/service:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve all services'
|
|
tags:
|
|
- internal-api
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/serviceObject"
|
|
/service/find-services-by-name:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Find a service by name'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- name: service_name
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
active:
|
|
type: boolean
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
research_mode:
|
|
type: boolean
|
|
restricted:
|
|
type: boolean
|
|
/service/live-services-data:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Unsure'
|
|
tags:
|
|
- internal-api
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
/service/{uuid}:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve details of a single service'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: "#/components/schemas/serviceObject"
|
|
/service/{uuid}/statistics:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve statistics about messages sent by a service'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
/service/{uuid}/api-keys:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve api-keys for a service'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/apiKeyResponse"
|
|
/service/{uuid}/api-keys/{key-id}:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve details of a single API key'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
- name: key-id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/apiKeyResponse"
|
|
/service/{uuid}/users:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Retrieve users associated with this service'
|
|
tags:
|
|
- internal-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/userObject"
|
|
/v2/templates:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Get list of templates'
|
|
tags:
|
|
- external-api
|
|
parameters:
|
|
- name: type
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: ["sms", "email"]
|
|
examples:
|
|
"SMS Templates":
|
|
value: "sms"
|
|
"Email Templates":
|
|
value: "email"
|
|
"All Templates":
|
|
value: ""
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
templates:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/templateObject"
|
|
/v2/template/{uuid}:
|
|
get:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Get details for a single template'
|
|
tags:
|
|
- external-api
|
|
parameters:
|
|
- $ref: "#/components/parameters/uuidPath"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/templateObject"
|
|
/v2/notifications/sms:
|
|
post:
|
|
security:
|
|
- bearerAuth: []
|
|
description: 'Send an SMS message to a single phone number'
|
|
tags:
|
|
- external-api
|
|
requestBody:
|
|
required: true
|
|
description: |
|
|
The request body is a JSON object giving at least the phone nubmer to
|
|
deliver the message to and the template ID to send to that number.
|
|
|
|
If the template has variables, provide them in the `personalisation`
|
|
object with the variable names as the object keys.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- phone_number
|
|
- template_id
|
|
properties:
|
|
phone_number:
|
|
type: string
|
|
template_id:
|
|
type: string
|
|
personalisation:
|
|
type: object
|
|
reference:
|
|
type: string
|
|
example:
|
|
phone_number: "800-555-0100"
|
|
template_id: "85b58733-7ebf-494e-bee2-a21a4ce17d58"
|
|
personalisation:
|
|
variable: "value"
|
|
responses:
|
|
'201':
|
|
description: Sent
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
content:
|
|
type: object
|
|
properties:
|
|
body:
|
|
type: string
|
|
from_number:
|
|
type: string
|
|
required:
|
|
- body
|
|
- from_number
|
|
additionalProperties: false
|
|
id:
|
|
type: string
|
|
reference:
|
|
type: string
|
|
scheduled_for:
|
|
type: string
|
|
template:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
uri:
|
|
type: string
|
|
version:
|
|
type: integer
|
|
required:
|
|
- id
|
|
- uri
|
|
- version
|
|
additionalProperties: false
|
|
uri:
|
|
type: string
|
|
additionalProperties: false
|
|
required:
|
|
- content
|
|
- id
|
|
- reference
|
|
- template
|
|
- uri
|