NudgeLink Accounts API
The accounts API from NudgeLink — 6 operation(s) for accounts.
The accounts API from NudgeLink — 6 operation(s) for accounts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nudgelink-co:nudgelink-co-accounts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NudgeLink Accounts API
version: 0.1.0
tags:
- name: Accounts
paths:
/api/v1/accounts/{account_id}:
patch:
tags:
- Accounts
summary: Update Account
description: 'Edit account settings (timezone, invite pace, sending window). Scoped
to the caller''s own accounts.
The timezone and window decide WHEN automatic actions go out; the
daily-cap day boundary stays UTC (locked decision #7).'
operationId: update_account_api_v1_accounts__account_id__patch
security:
- HTTPBearer: []
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccountRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LinkedInAccountOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Accounts
summary: Delete Account
description: '2026-06-12 (#43): remove a connected LinkedIn account.
Order of operations (safety-first):
1. Ownership check — 404 for anyone else''s account (no existence leak).
2. Pause every non-terminal sequence routed through this account, with
an explicit pause_reason so the leads page explains itself. The FK is
``SET NULL`` on delete, so without this step live sequences would
silently lose their sending seat and stall with no explanation.
3. Best-effort disconnect of the seat at Unipile (so the LinkedIn
session is actually severed, not just hidden from our UI). A
provider failure does NOT block the local delete — the user asked
for the account to be gone; we log and continue.
4. Delete the row.'
operationId: delete_account_api_v1_accounts__account_id__delete
security:
- HTTPBearer: []
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/accounts:
get:
tags:
- Accounts
summary: List Accounts
operationId: list_accounts_api_v1_accounts_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/LinkedInAccountOut'
type: array
title: Response List Accounts Api V1 Accounts Get
security:
- HTTPBearer: []
post:
tags:
- Accounts
summary: Connect Account
description: 'Connect a LinkedIn account via the manual-paste fallback flow.
Most customers go through the one-click hosted-auth flow (``start-connect``
above + the Unipile webhook). This endpoint is the escape hatch for:
- Tim manually attaching an account he created in the Unipile dashboard
- Pilot customers debugging issues where the hosted-auth webhook
didn''t fire
- Internal automated tests
Flow:
1. Reject duplicates: if a row with the same external_account_id already
exists for this client, return 409 (avoids accidentally creating
double-billing rows on retry).
2. Probe Unipile with check_account_health. We allow ``warming`` /
``requires_action`` / unknown statuses through (just create the row
in ``warming`` state — the P1.3 poller will reconcile). Only an
actual network/auth error blocks creation.
3. Always release the per-call adapter so we never leak the httpx
connection pool — every call to ``get_linkedin_adapter()`` returns
a fresh instance, so aclose() is mandatory.'
operationId: connect_account_api_v1_accounts_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectLinkedInRequest'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LinkedInAccountOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/accounts/{account_id}/profile-checklist:
get:
tags:
- Accounts
summary: Profile Checklist
description: 'How ready this seat''s own LinkedIn profile is to get invites accepted (2026-11-03).
Cached a day; ``items`` is null when the profile could not be read.'
operationId: profile_checklist_api_v1_accounts__account_id__profile_checklist_get
security:
- HTTPBearer: []
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/app__api__accounts__ChecklistOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/accounts/start-connect:
post:
tags:
- Accounts
summary: Start Connect
description: 'P1.1 — kick off self-serve LinkedIn connect via Unipile hosted auth.
Returns a one-time URL the customer should be redirected to. They log
into LinkedIn on Unipile-hosted pages (Unipile handles credential
capture, 2FA, proxy assignment). On success Unipile webhooks our
``POST /api/v1/webhooks/unipile/account-connected`` handler with the
new ``account_id``; we then create the LinkedInAccount row.
The customer never sees Tim, Tim never touches the credentials.'
operationId: start_connect_api_v1_accounts_start_connect_post
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/StartConnectRequest'
- type: 'null'
title: Req
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StartConnectResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/accounts/{account_id}/pause:
post:
tags:
- Accounts
summary: Pause Account
operationId: pause_account_api_v1_accounts__account_id__pause_post
security:
- HTTPBearer: []
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response Pause Account Api V1 Accounts Account Id Pause Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/accounts/{account_id}/resume:
post:
tags:
- Accounts
summary: Resume Account
operationId: resume_account_api_v1_accounts__account_id__resume_post
security:
- HTTPBearer: []
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response Resume Account Api V1 Accounts Account Id Resume Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
LinkedInAccountStatus:
type: string
enum:
- active
- warming
- paused_by_client
- paused_by_system
- requires_action
- banned
title: LinkedInAccountStatus
LinkedInAccountOut:
properties:
id:
type: string
format: uuid
title: Id
label:
type: string
title: Label
external_account_id:
anyOf:
- type: string
- type: 'null'
title: External Account Id
profile_url:
anyOf:
- type: string
- type: 'null'
title: Profile Url
status:
$ref: '#/components/schemas/LinkedInAccountStatus'
warmup_week:
type: integer
title: Warmup Week
daily_limits:
anyOf:
- additionalProperties:
type: integer
type: object
- type: 'null'
title: Daily Limits
daily_invite_cap:
type: integer
title: Daily Invite Cap
timezone:
type: string
title: Timezone
default: UTC
invite_pace:
type: string
title: Invite Pace
default: safe
send_hour_start:
type: integer
title: Send Hour Start
default: 8
send_hour_end:
type: integer
title: Send Hour End
default: 20
send_days:
items:
type: integer
type: array
title: Send Days
default:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
last_action_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Action At
ban_count:
type: integer
title: Ban Count
created_at:
type: string
format: date-time
title: Created At
is_premium:
anyOf:
- type: boolean
- type: 'null'
title: Is Premium
premium_kind:
anyOf:
- type: string
- type: 'null'
title: Premium Kind
type: object
required:
- id
- label
- external_account_id
- profile_url
- status
- warmup_week
- daily_limits
- daily_invite_cap
- last_action_at
- ban_count
- created_at
title: LinkedInAccountOut
ChecklistItem:
properties:
key:
type: string
title: Key
ok:
type: boolean
title: Ok
type: object
required:
- key
- ok
title: ChecklistItem
StartConnectResponse:
properties:
url:
type: string
title: Url
expires_at:
type: string
format: date-time
title: Expires At
type: object
required:
- url
- expires_at
title: StartConnectResponse
StartConnectRequest:
properties:
return_to:
type: string
enum:
- wizard
- accounts
title: Return To
default: accounts
timezone:
anyOf:
- type: string
maxLength: 64
- type: 'null'
title: Timezone
type: object
title: StartConnectRequest
description: 'Activation P0 (spec §4.2): strict origin-context enum. The wizard and
the Accounts page share hosted auth, but the callback pages need to know
where to send the user back. A closed enum — never an arbitrary URL — so
no open redirect can be injected.'
UpdateAccountRequest:
properties:
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
invite_pace:
anyOf:
- type: string
enum:
- safe
- faster
- type: 'null'
title: Invite Pace
send_hour_start:
anyOf:
- type: integer
maximum: 23.0
minimum: 0.0
- type: 'null'
title: Send Hour Start
send_hour_end:
anyOf:
- type: integer
maximum: 24.0
minimum: 1.0
- type: 'null'
title: Send Hour End
send_days:
anyOf:
- items:
type: integer
type: array
maxItems: 31
- type: 'null'
title: Send Days
type: object
title: UpdateAccountRequest
description: 'Editable per-account settings: the IANA timezone (Task 4, Alembic 037),
the invite pace (2026-09-28, Alembic 058) and the sending window
(2026-10-06, Alembic 065). Send any subset; the window''s three fields are
validated together against the stored values.'
ConnectLinkedInRequest:
properties:
label:
type: string
maxLength: 255
title: Label
default: ''
external_account_id:
type: string
maxLength: 128
title: External Account Id
profile_url:
type: string
maxLength: 512
title: Profile Url
default: ''
timezone:
anyOf:
- type: string
maxLength: 64
- type: 'null'
title: Timezone
type: object
required:
- external_account_id
title: ConnectLinkedInRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
app__api__accounts__ChecklistOut:
properties:
items:
anyOf:
- items:
$ref: '#/components/schemas/ChecklistItem'
type: array
- type: 'null'
title: Items
type: object
title: ChecklistOut
securitySchemes:
HTTPBearer:
type: http
scheme: bearer