openapi: 3.0.0
info:
title: Argyle Accounts Identities API
version: '2.0'
description: RESTful API providing user-consented access to payroll and employment data including identities, paystubs, gigs, shifts, vehicles, ratings, payroll documents, and deposit destinations across thousands of employers and gig platforms.
contact:
name: Argyle Support
url: https://docs.argyle.com/
x-api-id: argyle
x-audience: public
servers:
- url: https://api.argyle.com
description: Production
- url: https://api-sandbox.argyle.com
description: Sandbox
security:
- basicAuth: []
tags:
- name: Identities
paths:
/v2/identities/{id}:
get:
summary: Retrieve an identity
description: Retrieves an identity object.
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: ID of the identity object to be retrieved.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Identity'
example:
id: 0153b145-7ab9-bea2-cc16-a8b71328942f
account: 0187c66e-e7e5-811c-b006-2232f00f426a
address:
city: New York
line1: 852 North W St
line2: Apt 221
state: NY
country: US
postal_code: '10014'
first_name: Sarah
last_name: Longfield
full_name: Sarah Longfield
birth_date: '1980-10-30'
email: '[email protected]'
phone_number: '+12125555555'
picture_url: www.argyle.com/logofoldername
employment_status: active
employment_type: full-time
job_title: Store Manager
ssn: 522-09-1191
marital_status: Married filing jointly
gender: Female
original_hire_date: '2019-01-03'
hire_date: '2020-04-08'
termination_date: null
termination_reason: null
employer: Whole Goods
employment: 0183d52a-d3b2-331d-c753-3662a20e352b
base_pay:
amount: '58024.50'
period: annual
currency: USD
pay_cycle: semimonthly
platform_ids:
employee_id: OB238HDW5
position_id: 6ELL4O7PM
platform_user_id: JLH7B9V6O6YGN9O7
created_at: '2023-01-30T12:53:24.561594Z'
updated_at: '2023-01-30T12:55:06.478699Z'
metadata: {}
tags:
- Identities
/v2/identities:
get:
summary: List all identities
description: Returns a paginated list of all identity objects.
parameters:
- in: query
name: account
schema:
type: string
format: uuid
description: Filter by account ID.
- in: query
name: user
schema:
type: string
format: uuid
description: Filter by user ID.
- in: query
name: employment
schema:
type: string
format: uuid
description: Filter by employment ID.
- in: query
name: limit
schema:
type: integer
description: 'Number of identity objects returned per page. Default: 10. Maximum: 200.
'
- 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/Identity'
example:
next: https://api-sandbox.argyle.com/v2/identities?cursor=ZXhhbXBsZV9jdXJzb3I
previous: null
results:
- id: 0186da0b-6569-0ea0-eb50-b64e97cb29e9
account: 0186da0b-9923-0d27-4b05-6ce3b7b07b89
address:
city: San Diego
line1: 54 N Shea Ridge
line2: null
state: CA
country: US
postal_code: '92092'
first_name: Joe
last_name: Burnam
full_name: Joe Burnam
birth_date: '1978-08-29'
email: '[email protected]'
phone_number: '+12123338708'
picture_url: www.argyle.com/logofoldername
employment_status: active
employment_type: part-time
job_title: Hourly staff
ssn: 301-06-1225
marital_status: Married filing jointly
gender: Male
original_hire_date: '2022-05-18'
hire_date: '2022-05-18'
termination_date: null
termination_reason: null
employer: Double Double
employment: 0183d52a-d3b2-331d-c753-3662a20e352b
base_pay:
amount: '18.08'
period: hourly
currency: USD
pay_cycle: monthly
platform_ids:
employee_id: 32ULINA8
position_id: 67LKUKA8
platform_user_id: '332512349952'
created_at: '2023-01-31T12:13:24.561594Z'
updated_at: '2023-01-31T12:45:06.478699Z'
metadata: {}
- id: 0353c142-4ab9-baa1-cb44-c8b51225877e
account: 0185a8b8-60eb-80ca-7482-5f24504573f7
address:
city: Oklahoma City
line1: 312 Main Ave
line2: null
state: OK
country: US
postal_code: '73008'
first_name: Bob
last_name: Jones
full_name: Bob Jones
birth_date: '1983-07-02'
email: '[email protected]'
phone_number: '+13228675309'
picture_url: www.argyle.com/logofoldername
employment_status: active
employment_type: contractor
job_title: Data analyst
ssn: 507-18-3058
marital_status: Single
gender: Female
original_hire_date: '2019-01-03'
hire_date: '2021-04-08'
termination_date: null
termination_reason: null
employer: Half Bads
employment: 0183d52a-d3b2-331d-c753-3662a20e352b
base_pay:
amount: '39.72'
period: hourly
currency: USD
pay_cycle: biweekly
platform_ids:
employee_id: bd823Lk
position_id: ab3EkU2
platform_user_id: '832355'
created_at: '2023-01-30T13:53:24.561594Z'
updated_at: '2023-01-30T13:55:06.478699Z'
metadata: {}
tags:
- Identities
components:
schemas:
Identity:
type: object
example:
id: 0153b145-7ab9-bea2-cc16-a8b71328942f
account: 0187c66e-e7e5-811c-b006-2232f00f426a
address:
city: New York
line1: 852 North W St
line2: Apt 221
state: NY
country: US
postal_code: '10014'
first_name: Sarah
last_name: Longfield
full_name: Sarah Longfield
birth_date: '1980-10-30'
email: sarah@email.com
phone_number: '+12125555555'
picture_url: www.argyle.com/logofoldername
employment_status: active
employment_type: full-time
job_title: Store Manager
ssn: 522-09-1191
marital_status: Married filing jointly
gender: Female
original_hire_date: '2019-01-03'
hire_date: '2020-04-08'
termination_date: null
termination_reason: null
employer: Whole Goods
employment: 0183d52a-d3b2-331d-c753-3662a20e352b
base_pay:
amount: '58024.50'
period: annual
currency: USD
pay_cycle: semimonthly
platform_ids:
employee_id: OB238HDW5
position_id: 6ELL4O7PM
platform_user_id: JLH7B9V6O6YGN9O7
created_at: '2023-01-30T12:53:24.561Z'
updated_at: '2023-01-30T12:55:06.478Z'
metadata: null
properties:
id:
type: string
format: uuid
description: Unique ID of the identity.
example: 0153b145-7ab9-bea2-cc16-a8b71328942f
account:
type: string
format: uuid
description: ID of the account associated with the identity.
example: 0187c66e-e7e5-811c-b006-2232f00f426a
address:
$ref: '#/components/schemas/Address'
first_name:
type: string
description: First name of the employee. Usually the legal first name.
example: Sarah
last_name:
type: string
description: Last name of the employee. Usually the legal last name.
example: Longfield
full_name:
type: string
description: Full name of the employee. Sourced from payroll data if available, otherwise constructed from available names and suffixes.
example: Sarah Longfield
birth_date:
type: string
format: date
description: 'Date of birth in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If values are obfuscated (rare), a dash will replace the value (e.g. --01-31 when the year is obfuscated).
'
example: '1980-10-30'
email:
type: string
description: Email address.
example: '[email protected]'
phone_number:
type: string
description: 'Phone number [E.164](https://en.wikipedia.org/wiki/E.164) international format).
'
example: '+12125555555'
picture_url:
type: string
description: URL location of the user's profile image.
example: www.argyle.com/logofoldername
employment_status:
type: string
enum:
- active
- inactive
- terminated
description: "Job status of the employment relevant to the identity.\n\n- Definitions of `inactive` and `terminated` vary by Item and can overlap.\n - `inactive` typically indicates the employee left voluntarily, is on leave, or has not been active for a certain period of time.\n - `terminated` typically indicates the employee is no longer employed. Specific reasons for termination, if available, are returned in the `termination_reason` field.\n- We recommend using data from the `/paystubs` and `/gigs` endpoints to construct a more wholistic timeline of employment history.\n"
example: active
employment_type:
type: string
enum:
- full-time
- part-time
- contractor
- military
- benefits
- seasonal
- temporary
- regular
- other
description: "Type of employment.\n\n<details class=\"enum-definitions\">\n<summary>Employment type enum definitions</summary>\n\n- `full-time`\n - Employment in which an individual is regularly scheduled to work 30 or more hours per week, or meets the employer's internal threshold for a standard full-time workweek.\n - **Examples:** `full-time employee`, `36+ hours weekly`\n- `part-time`\n - Employment in which an individual is regularly scheduled to work fewer than 30 hours per week, or meets the employer's internal threshold for a standard part-time workweek.\n - **Examples:** `PT regular`, `20+ hours weekly`\n- `contractor`\n - Work performed by an individual engaged for a specific project or timeframe who is not an employee of the organization.\n - **Examples:** `gig worker`, `contract employee`, `contract worker`, `freelancer`\n- `military`\n - Compensation derived from active-duty or reserve military service.\n - *Automatically set for military platforms.*\n- `benefits`\n - Non-wage compensation or government-issued assistance.\n - *Automatically set for benefits platforms.*\n- `seasonal`\n - Employment that occurs at approximately the same time each year, typically lasting six months or less.\n - **Examples:** `seasonal on-call`, `seasonal part-time`, `peak seasonal`\n- `temporary`\n - Short-term employment with a defined end date, usually lasting one year or less.\n - **Examples:** `internship`, `substitute employee`, `temporary full-time`, `temporary part-time`\n- `regular`\n - Ongoing employment with no specified end date that does not fall into more specialized categories.\n - **Examples:** `permanent`, `W-2`, `salaried`\n- `other`\n - Work or income that does not fit standard classifications.\n - **Examples:** `variable`, `casual`, `employee`, `PRN (on-call)`\n\n</details>\n"
example: full-time
job_title:
type: string
description: Job title.
example: Store Manager
ssn:
type: string
description: Social Security number.
example: 522-09-1191
marital_status:
type: string
description: Marital status.
example: Married filing jointly
gender:
type: string
description: Gender.
example: Female
original_hire_date:
type: string
format: date
description: 'Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) of the user''s **earliest** employment start date.
'
example: '2019-01-03'
hire_date:
type: string
format: date
description: 'Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) of the user''s **most recent** employment start date.
`hire_date` may differ from `original_hire_date` due to a promotion, a re-hiring event, or similar.
'
example: '2020-04-08'
termination_date:
type: string
format: date
nullable: true
description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the user was terminated.
example: null
termination_reason:
type: string
nullable: true
description: Reason for termination.
example: null
employer:
type: string
description: Name of the employer.
example: Whole Goods
employment:
type: string
description: '[Employment](/api-reference/employments) ID. Can be used as a filter when [listing identities](/api-reference/identities/list-all-identities).
'
example: 0183d52a-d3b2-331d-c753-3662a20e352b
base_pay:
$ref: '#/components/schemas/BasePay'
pay_cycle:
type: string
enum:
- daily
- weekly
- biweekly
- semimonthly
- monthly
- quarterly
description: 'Payment frequency.
- `daily`
- `weekly`
- `biweekly` — every two weeks
- `semimonthly` — twice a month
- `monthly`
- `quarterly`
'
example: semimonthly
platform_ids:
$ref: '#/components/schemas/PlatformIds'
created_at:
type: string
format: date-time
description: 'Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the identity object was created.
'
example: '2023-01-30T12:53:24.561594Z'
updated_at:
type: string
format: date-time
description: 'Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when a property value of the identity object most recently changed.
'
example: '2023-01-30T12:55:06.478699Z'
metadata:
type: object
description: Additional, non-categorized information.
example: {}
Address:
type: object
properties:
city:
type: string
description: Name of the city, town, district, or similar regional entity.
example: New York
line1:
type: string
description: Address-Line 1, usually street address or P.O. Box information.
example: 852 North W St
line2:
type: string
description: Address-Line 2, usually the apartment or unit number.
example: Apt 221
state:
type: string
description: State, county, province, region, or equivalent.
example: NY
country:
type: string
description: 'Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format).
'
example: US
postal_code:
type: string
description: Zip code, or equivalent.
example: '10014'
PlatformIds:
type: object
properties:
employee_id:
type: string
description: Internal user ID assigned by the employer.
example: OB238HDW5
position_id:
type: string
description: Internal position ID assigned by the employer.
example: 6ELL4O7PM
platform_user_id:
type: string
description: ID assigned by the payroll system.
example: JLH7B9V6O6YGN9O7
BasePay:
type: object
properties:
amount:
type: string
description: Defined pay amount per period. Does not include bonus, commission or similar incentive-based income.
example: '58024.50'
period:
type: string
enum:
- hourly
- daily
- weekly
- biweekly
- semimonthly
- monthly
- annual
- salary
description: 'Payment interval that specifically corresponds to the base pay `amount`.
- `hourly`
- `daily`
- `weekly`
- `biweekly` — every two weeks
- `semimonthly` — twice a month
- `monthly`
- `annual`
- `salary` — only when explicitly mentioned and no other pay period information is present
'
example: annual
currency:
type: string
description: 'Pay currency ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code).
'
example: USD
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Username = api_key_id, Password = api_key_secret