Create Link

Create a new link intent for account connection.

Request


POST /v1/links

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Body

Field	Type	Required	Description
`integrationId`	string	Yes	Integration identifier (e.g., `tmobile`, `att`, `verizon`, `ubereats`)
`resource`	string	Yes	Resource to access (e.g., `paymentMethod`, `mobileBillingStatement`, `orderHistory`)
`action`	string	Yes	Operation to perform (`read` or `write`)
`arguments`	object	No	Operation arguments — validated against the resource’s schema (see List Providers)
`webhookUrl`	string	No	URL to receive completion webhook (must be a valid URL)
`externalUserId`	string	No	Your identifier for the user
`debug`	boolean	No	Enable debug mode for this link
`expiresIn`	integer	No	Custom link expiry in seconds (default: 4 hours)

Response

201 Created


{
  "linkId": "link_abc123",
  "claimCode": "clm_xxx",
  "integrationId": "tmobile",
  "resource": "mobileBillingStatement",
  "action": "read",
  "status": "pending",
  "appClipUrl": "https://appclip.example.com/link_abc123?code=clm_xxx",
  "expiresAt": 1704081600000,
  "createdAt": 1704067200000
}

400 Bad Request

Returned when:

Required fields are missing or have wrong types
The webhookUrl is not a valid URL
The expiresIn is not a positive integer
The integrationId + resource + action combination is not valid
The arguments do not match the resource’s schema

Validation errors include structured details:


{
  "error": "Validation failed",
  "issues": [
    { "path": "webhookUrl", "message": "must be a valid URL" }
  ]
}

Notes

Creates a link record only — no session is spawned until the link is claimed
The appClipUrl contains the claim code and is passed to the client SDK to initiate the flow
Links expire after 4 hours by default, or after expiresIn seconds if specified
Use GET /v1/providers to discover valid integration/resource/action combinations and argument schemas