openapi: 3.0.0 info: title: Users API version: 1.0.0 description: | API for managing users. Users connect their payroll accounts using Link. security: - basicAuth: [] paths: /v2/users: post: summary: Create a user description: >- Creates a new user object. Includes a new [user token](/link/user-tokens) in the response. requestBody: content: application/json: example: {} schema: type: object properties: first_name: type: string description: Pre-fill Link's login screen with this first name. last_name: type: string description: Pre-fill Link's login screen with this last name. email: type: string description: > Pre-fill Link's login screen with this email. Invalid email addresses will cause the request to fail. We recommend client-side validation and retrying the request without the invalid email if you receive: ```json { "email": [ "Enter a valid email address." ] } ``` phone_number: type: string description: > Pre-fill Link's login screen with this phone number. E.164 international format recommended. Invalid phone numbers will cause the request to fail. We recommend client-side validation and retrying the request without the invalid phone number if you receive: ```json { "phone_number": [ "Enter a valid phone number." ] } ``` ssn: type: string description: Social Security number. address: type: object description: Address of the user. properties: city: type: string description: >- Name of the city, town, district, or similar regional entity. line1: type: string description: >- Address-Line 1, usually street address or P.O. Box information. line2: type: string description: Address-Line 2, usually the apartment or unit number. state: type: string description: State, county, province, region, or equivalent. country: type: string description: Two-letter country code (ISO 3166-1 alpha-2 format). postal_code: type: string description: Zip code, or equivalent. birth_date: type: object description: Date of birth of the user. properties: year: type: integer description: Birth year (1900 or later). month: type: integer description: Birth month (between 1 and 12). day: type: integer description: Birth day (between 1 and 31). external_metadata: type: object description: Any valid JSON. open_banking: type: object description: >- Can be optionally included when ordering [banking verifications](/api-reference/verifications-guide). properties: end_user: type: object description: >- Contains details about the person or entity making the lending decision. properties: name: type: string description: Name of the lender or entity. address: type: string description: >- Street address or P.O. Box information (include apartment or unit numbers). city: type: string description: >- Name of the city, town, district, or similar regional entity. state: type: string description: State, county, province, region, or equivalent. zip: type: string description: Zip code, or equivalent. phone: type: string description: | Phone number of the lender or entity. Must be 10 or 11 digits (with or without hyphens). external_id: type: string description: Any string. Maximum 100 characters. responses: '200': description: '' content: application/json: example: user_token: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIxNDRhMTRkNS04YzEzLTQzZGYtOTI4Ni01OWY4NjFkOWEyMDIiLCJleHAiOjE2NzgzNDExNDMsImZpZCI6ImIyYzY4YzUwLTc2MTQtNDAwNy1iMzNmLWZiMzlkMDFmMmM3MCIsImlhdCI6MTY3ODMzNzU0MywiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1kZXYiLCJqdGkiOiI3ZTU0ZTY1NS05YWN2LTRiZDctOWI3OC0xODMxMjVkYjM1MzMiLCJzdWIiOiIwMTg2YzRiNi04ZTgyLWQ5OWMtOGY4Mi1mNjMyMjgxMzk2ZTQiLCJ1c2VyX2lkIjoiMDE4NmM0YjYtOGU4Mi1kOTljLThmODItZjYzMjI4MTM5NmU0In0.q5bkZTFAohISOcjJDb2wSzKcHmwrOM4pp9imOVybaWk id: 018051aa-f7a9-a0db-2f38-6cfa325e9d69 schema: type: object properties: user_token: type: string description: Token associated with the created user. id: type: string format: uuid description: Unique ID of the user. get: summary: List all users description: Returns a paginated list of all user objects. parameters: - in: query name: limit schema: type: integer description: > Number of user objects returned [per page](/api-guide/overview#pagination). Default: 10. Maximum: 200. - in: query name: external_id schema: type: string description: Filter users by `external_id`. Exact matches only. - in: query name: cursor schema: type: string description: >- The URL returned in `next` or `previous` used to retrieve another [page](/api-guide/overview#pagination) of results. responses: '200': description: '' content: application/json: schema: type: object properties: next: type: string format: uri nullable: true description: URL for the next page of results, if available. previous: type: string format: uri nullable: true description: URL for the previous page of results, if available. results: type: array items: $ref: '#/components/schemas/User' example: next: >- https://api-sandbox.argyle.com/v2/users?cursor=ZXhhbXBsZV9jdXJzb3I previous: null results: - id: 018051aa-f7a9-a0db-2f38-6cfa325e9d69 created_at: '2023-01-30T22:25:38.971Z' items_connected: - item_123456789 - item_987654321 employers_connected: - Whole Goods - Bullseye external_metadata: notes: In stage 3 of loan approval. category: Summer Initiative external_id: July Connection first_name: Sarah last_name: Longfield email: sarah@email.com phone_number: '+12125555555' ssn: null address: city: null line1: null line2: null state: null country: null postal_code: null birth_date: year: null month: null day: null - id: 0186c5b8-8fa1-67b3-39af-14b3e18da8a7 created_at: '2023-01-30T23:25:38.971Z' items_connected: - item_000000001 - item_000000002 employers_connected: - Half Bads - Triple external_metadata: notes: In stage 1 of loan approval. category: Summer Initiative external_id: August Connection first_name: null last_name: null email: null phone_number: null ssn: null address: city: null line1: null line2: null state: null country: null postal_code: null birth_date: year: null month: null day: null /v2/users/{id}: get: summary: Retrieve a user description: Retrieves a user object. parameters: - in: path name: id required: true schema: type: string format: uuid description: ID of the user object to be retrieved. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/User' patch: summary: Update a user description: Updates a user object. parameters: - in: path name: id required: true schema: type: string format: uuid description: ID of the user object to be updated. requestBody: content: application/json: schema: type: object properties: first_name: type: string description: Pre-fill Link's login screen with this first name. last_name: type: string description: Pre-fill Link's login screen with this last name. email: type: string description: | Pre-fill Link's login screen with this email. Invalid email addresses will cause the request to fail. phone_number: type: string description: > Pre-fill Link's login screen with this phone number. [E.164](https://en.wikipedia.org/wiki/E.164) international format recommended. Invalid phone numbers will cause the request to fail. ssn: type: string description: Social Security number. address: type: object properties: city: type: string description: >- Name of the city, town, district, or similar regional entity. line1: type: string description: >- Address-Line 1, usually street address or P.O. Box information. line2: type: string description: Address-Line 2, usually the apartment or unit number. state: type: string description: State, county, province, region, or equivalent. country: type: string description: >- Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). postal_code: type: string description: Zip code, or equivalent. birth_date: type: object properties: year: type: integer description: Birth year (1900 or later). month: type: integer description: Birth month (between 1 and 12). day: type: integer description: Birth day (between 1 and 31). external_metadata: type: object description: > Any valid JSON. Must be an object `{}` when used for [banking reports](/api-reference/banking-overview#create-an-argyle-user). open_banking: type: object description: >- Only relevant to [banking reports](/api-reference/banking-overview#create-an-argyle-user). properties: end_user: type: object description: >- Contains details about the person or entity making the lending decision. properties: name: type: string description: Name of the lender or entity. address: type: string description: >- Street address or P.O. Box information (include apartment or unit numbers). city: type: string description: >- Name of the city, town, district, or similar regional entity. state: type: string description: State, county, province, region, or equivalent. zip: type: string description: Zip code, or equivalent. phone: type: string description: | Phone number of the lender or entity. Must be 10 or 11 digits (with or without hyphens). external_id: type: string description: Any string. Maximum 100 characters. example: first_name: Sarah last_name: Longfield email: sarah@email.com phone_number: '+12125555555' external_metadata: notes: Moved to stage 2 of loan approval. category: Summer Initiative external_id: July_Connection responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/User' delete: summary: Delete a user description: > Deletes a user object. Deleting a user object will also delete all accounts and resources associated with the user. parameters: - in: path name: id required: true schema: type: string format: uuid description: ID of the user object to be deleted. responses: '204': description: '204 status code: No content.' components: securitySchemes: basicAuth: type: http scheme: basic description: Username = api_key_id, Password = api_key_secret schemas: User: type: object properties: id: type: string format: uuid description: Unique ID of the user. example: 018051aa-f7a9-a0db-2f38-6cfa325e9d69 created_at: type: string format: date-time description: Timestamp (ISO 8601) when the user object was created. example: '2023-01-30T22:25:38.971Z' items_connected: type: array items: type: string description: >- Items the user has connected through Link. Typically employers or payroll platforms. example: - item_123456789 - item_987654321 employers_connected: type: array items: type: string description: Individual employers associated with the connected Items. example: - Whole Goods - Bullseye external_metadata: type: object description: > Free-text field where additional context for the user can be added. - Can be any valid JSON, such as a string or object. Using `external_id` (see below) is recommended when the ability to filter users by an external value is needed. example: notes: Moved to stage 2 of loan approval. category: Summer Initiative external_id: type: string description: > Free-text field where [additional context](/overview/data-structure/users#external-identifiers) for the user can be added. - Can be any string of 100 characters or less. - Multiple users can have the same `external_id`. Often used to group users, or associate your internal ID's to users. - Can be attached to [invites](/console/flows/email-sms-templates#inviting-new-users) or [shareable URLs](/console/flows/shareable-urls#customizations). - Can be used as a query parameter when [listing users](/api-reference/users#list). (Only exact matches are supported) - Can be used to search for specific users within the [Connections](https://console.argyle.com/connections) section of Console. - Will appear on billing CSVs if associated with a user. example: July_Connection first_name: type: string description: First name of the user. example: Sarah last_name: type: string description: Last name of the user. example: Longfield email: type: string description: Email of the user. example: sarah@email.com phone_number: type: string description: Phone number of the user. E.164 international format. example: '+12125555555' ssn: type: string description: Social Security number of the user. example: null address: type: object description: Address of the user. properties: city: type: string description: Name of the city, town, district, or similar regional entity. example: null line1: type: string description: Address-Line 1, usually street address or P.O. Box information. example: null line2: type: string description: Address-Line 2, usually the apartment or unit number. example: null state: type: string description: State, county, province, region, or equivalent. example: null country: type: string description: Two-letter country code (ISO 3166-1 alpha-2 format). example: null postal_code: type: string description: Zip code, or equivalent. example: null birth_date: type: object description: Date of birth of the user. properties: year: type: integer description: Birth year (1900 or later). example: null month: type: integer description: Birth month (between 1 and 12). example: null day: type: integer description: Birth day (between 1 and 31). example: null