Users

Users connect their payroll accounts using Link.

#The user object

Attributes

#
idstring (uuid)
Unique ID of the user.
#
created_atstring (datetime)
Timestamp (ISO 8601) when the user object was created.
#
items_connectedarray of strings
Items the user has connected through Link. Typically employers or payroll platforms.
#
employers_connectedarray of strings
Individual employers associated with the connected Items.
#
external_metadataJSON
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.
#
external_idstring
Free-text field where additional context 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 or shareable URLs.
— Can be used as a query parameter when listing users. (Only exact matches are supported)
— Can be used to search for specific users within the Connections section of Console.
— Will appear on billing CSVs if associated with a user.
#
first_namestring
First name of the user.
#
last_namestring
Last name of the user.
#
emailstring
Email of the user.
#
phone_numberstring
Phone number of the user. E.164 international format.
#
ssnstring
Social Security number of the user.

addressobject

Address of the user.

citystring

Name of the city, town, district, or similar regional entity.

line1string

Address-Line 1, usually street address or P.O. Box information.

line2string

Address-Line 2, usually the apartment or unit number.

statestring

State, county, province, region, or equivalent.

countrystring

Two-letter country code (ISO 3166-1 alpha-2 format).

postal_codestring

Zip code, or equivalent.

birth_dateobject

Date of birth of the user.

yearinteger

Birth year (1900 or later).

monthinteger

Birth month (between 1 and 12).

dayinteger

Birth day (between 1 and 31).

Example

1{
2  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
3  "created_at": "2023-01-30T22:25:38.971210Z",
4  "items_connected": [
5    "item_123456789",
6    "item_987654321"
7  ],
8  "employers_connected": [
9    "Whole Goods",
10    "Bullseye"
11  ],
12  "external_metadata": {
13    "notes": "In stage 1 of loan approval.",
14    "category": "Summer Initiative"
15  },
16  "external_id": "July_Connection",
17  "first_name": "Sarah",
18  "last_name": "Longfield",
19  "email": "[email protected]",
20  "phone_number": "+12125555555",
21  "ssn": null,
22  "address": {
23    "city": null,
24    "line1": null,
25    "line2": null,
26    "state": null,
27    "country": null,
28    "postal_code": null
29  },
30  "birth_date": {
31    "year": null,
32    "month": null,
33    "day": null
34  }
35}

#Create a user

post/v2/users

Creates a new user object.

Includes a new user token in the response.

Request body

#
first_namestring
optional
Pre-fill Link's login screen with this first name.
#
last_namestring
optional
Pre-fill Link's login screen with this last name.
#
emailstring
optional
Pre-fill Link's login screen with this email.
Invalid email addresses will cause the request to fail.

We recommend implementing client-side email address validation and including a retry method in your applications that removes the invalid email address in response to the following 400 status code:
1{ 2 "email": [ 3 "Enter a valid email address." 4 ] 5}
#
phone_numberstring
optional
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 implementing client-side phone number validation and including a retry method in your applications that removes the invalid phone number in response to the following 400 status code:
1{ 2 "phone_number": [ 3 "Enter a valid phone number." 4 ] 5}
#
ssnstring
optional
Social Security number.
Required for banking reports.

addressobject

optional

Required for banking reports.

citystring

optional

Name of the city, town, district, or similar regional entity.

line1string

optional

Address-Line 1, usually street address or P.O. Box information.

line2string

optional

Address-Line 2, usually the apartment or unit number.

statestring

optional

State, county, province, region, or equivalent.

countrystring

optional

Two-letter country code (ISO 3166-1 alpha-2 format).

postal_codestring

optional

Zip code, or equivalent.

birth_dateobject

optional

Required for banking reports.

yearinteger

optional

Birth year (1900 or later).

monthinteger

optional

Birth month (between 1 and 12).

dayinteger

optional

Birth day (between 1 and 31).

#
external_metadataJSON
optional
Any valid JSON.
Must be an object {} when used for banking reports.

open_bankingobject

optional

Required for banking reports.

end_userobject

required

Contains details about the person or entity making the lending decision.

namestring

required

Name of the lender or entity.

addressstring

required

Street address or P.O. Box information (include apartment or unit numbers).

citystring

required

Name of the city, town, district, or similar regional entity.

statestring

required

State, county, province, region, or equivalent.

zipstring

required

Zip code, or equivalent.

phonestring

required

Phone number of the lender or entity.

Must be 10 or 11 digits (with or without hyphens).

#
external_idstring
optional
Any string. Maximum 100 characters.

Example Request

1curl --request POST \
2     --url https://api.argyle.com/v2/users \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'

Example Response

1{
2  "user_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIxNCRhMTRkNS04YzEzLTQzZGYtOTI4Ni01OWY4NjFkOWEyMDIiLCJleHAiOjE2NzgzNDExNDMsImZpZCI6ImIyYzY4YzUwLTc2MTQtNDAwNy1iMzNmLWZiMzlkMDFmMmM3MCIsImlhdCI6MTY3ODMzNzU0MywiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1kZXYiLCJqdGkiOiI3ZTU0ZTY1NS05YWN2LTRiZDctOWI3OC0xODMxMjVkYjM1MzMiLCJzdWIiOiIwMTg2YzRiNi04ZTgyLWQ5OWMtOGY4Mi1mNjMyMjgxMzk2ZTQiLCJ1c2VyX2lkIjoiMDE4NmM0YjYtOGU4Mi1kOTljLThmODItZjYzMjI4MTM5NmU0In0.q5bkZTFAohISOcjJDb2wSzKcHmwrOM4pp9imOVybaWk",
3  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"
4}

#Retrieve a user

get/v2/users/{id}

Retrieves a user object.

Path parameters

#
idstring (uuid)
required
ID of the user object to be retrieved.

Example Request

1curl --request GET \
2     --url https://api.argyle.com/v2/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'

Example Response

1{
2  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
3  "created_at": "2023-03-09T04:54:35.170468Z",
4  "items_connected": [
5    "item_123456789",
6    "item_987654321"
7  ],
8  "employers_connected": [
9    "Whole Goods",
10    "Bullseye"
11  ],
12  "external_metadata": {},
13  "external_id": null,
14  "first_name": "Sarah",
15  "last_name": "Longfield",
16  "email": "[email protected]",
17  "phone_number": "+12125555555",
18  "ssn": null,
19  "address": {
20    "city": null,
21    "line1": null,
22    "line2": null,
23    "state": null,
24    "country": null,
25    "postal_code": null
26  },
27  "birth_date": {
28    "year": null,
29    "month": null,
30    "day": null
31  }
32}

#Update a user

patch/v2/users/{id}

Updates a user object.

Path parameters

#
idstring (uuid)
required
ID of the user object to be updated.

Request body

#
first_namestring
optional
Pre-fill Link's login screen with this first name.
#
last_namestring
optional
Pre-fill Link's login screen with this last name.
#
emailstring
optional
Pre-fill Link's login screen with this email.
Invalid email addresses will cause the request to fail.

We recommend implementing client-side email address validation and including a retry method in your applications that removes the invalid email address in response to the following 400 status code:
1{ 2 "email": [ 3 "Enter a valid email address." 4 ] 5}
#
phone_numberstring
optional
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 implementing client-side phone number validation and including a retry method in your applications that removes the invalid phone number in response to the following 400 status code:
1{ 2 "phone_number": [ 3 "Enter a valid phone number." 4 ] 5}
#
ssnstring
optional
Social Security number.

addressobject

optional

citystring

optional

Name of the city, town, district, or similar regional entity.

line1string

optional

Address-Line 1, usually street address or P.O. Box information.

line2string

optional

Address-Line 2, usually the apartment or unit number.

statestring

optional

State, county, province, region, or equivalent.

countrystring

optional

Two-letter country code (ISO 3166-1 alpha-2 format).

postal_codestring

optional

Zip code, or equivalent.

birth_dateobject

optional

yearinteger

optional

Birth year (1900 or later).

monthinteger

optional

Birth month (between 1 and 12).

dayinteger

optional

Birth day (between 1 and 31).

#
external_metadataJSON
optional
Any valid JSON.
Must be an object {} when used for banking reports.

open_bankingobject

optional

Only relevant to banking reports.

end_userobject

required

Contains details about the person or entity making the lending decision.

namestring

required

Name of the lender or entity.

addressstring

required

Street address or P.O. Box information (include apartment or unit numbers).

citystring

required

Name of the city, town, district, or similar regional entity.

statestring

required

State, county, province, region, or equivalent.

zipstring

required

Zip code, or equivalent.

phonestring

required

Phone number of the lender or entity.

Must be 10 or 11 digits (with or without hyphens).

#
external_idstring
optional
Any string. Maximum 100 characters.

Example Request

1curl --request PATCH \
2     --url https://api.argyle.com/v2/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{"external_metadata": {}}'

Example Response

1{
2  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
3  "created_at": "2023-03-09T04:54:35.170468Z",
4  "items_connected": [
5    "item_123456789",
6    "item_987654321"
7  ],
8  "employers_connected": [
9    "Whole Goods",
10    "Bullseye"
11  ],
12  "external_metadata": {
13    "notes": "Moved to stage 2 of loan approval.",
14    "category": "Summer Initiative"
15  },
16  "external_id": "July_Connection",
17  "first_name": "Sarah",
18  "last_name": "Longfield",
19  "email": "[email protected]",
20  "phone_number": "+12125555555",
21  "ssn": null,
22  "address": {
23    "city": null,
24    "line1": null,
25    "line2": null,
26    "state": null,
27    "country": null,
28    "postal_code": null
29  },
30  "birth_date": {
31    "year": null,
32    "month": null,
33    "day": null
34  }
35}

#Delete a user

delete/v2/users/{id}

Deletes a user object.

Caution — Deleting a user object will also delete all accounts and resources associated with the user.

Path parameters

#
idstring (uuid)
required
ID of the user object to be deleted.

Example Request

1curl --request DELETE \
2     --url https://api.argyle.com/v2/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'

Example Response

1"204 status code: No content."

#List all users

get/v2/users

Returns an array of all user objects.

Query parameters

#
limitinteger
optional
Number of user objects returned per page. Default: 10. Maximum: 200.
#
external_idstring
optional
Filter users by external_id. Exact matches only.

Example Request

1curl --request GET \
2     --url https://api.argyle.com/v2/users?limit=2 \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'

Example Response

1[
2  {
3    "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4    "created_at": "2023-01-30T22:25:38.971210Z",
5    "items_connected": [
6      "item_123456789",
7      "item_987654321"
8    ],
9    "employers_connected": [
10      "Whole Goods",
11      "Bullseye"
12    ],
13    "external_metadata": {
14      "notes": "In stage 3 of loan approval.",
15      "category": "Summer Initiative"
16    },
17    "external_id": "July Connection",
18    "first_name": "Sarah",
19    "last_name": "Longfield",
20    "email": "[email protected]",
21    "phone_number": "+12125555555",
22    "ssn": null,
23    "address": {
24      "city": null,
25      "line1": null,
26      "line2": null,
27      "state": null,
28      "country": null,
29      "postal_code": null
30    },
31    "birth_date": {
32      "year": null,
33      "month": null,
34      "day": null
35    }
36  },
37  {
38    "id": "0186c5b8-8fa1-67b3-39af-14b3e18da8a7",
39    "created_at": "2023-01-30T23:25:38.971210Z",
40    "items_connected": [
41      "item_000000001",
42      "item_000000002"
43    ],
44    "employers_connected": [
45      "Half Bads",
46      "Triple"
47    ],
48    "external_metadata": {
49      "notes": "In stage 1 of loan approval.",
50      "category": "Summer Initiative"
51    },
52    "external_id": "August Connection",
53    "first_name": null,
54    "last_name": null,
55    "email": null,
56    "phone_number": null,
57    "ssn": null,
58    "address": {
59      "city": null,
60      "line1": null,
61      "line2": null,
62      "state": null,
63      "country": null,
64      "postal_code": null
65    },
66    "birth_date": {
67      "year": null,
68      "month": null,
69      "day": null
70    }
71  }
72]

Data Structure

Flows

Management

Reference

POS & LOS Systems

Day 1 Certainty® and AIM

Document Processing

Verification of Income and Employment

Deposit Switching

Paycheck-linked Lending

Getting Started

Argyle Link

Argyle Console

Troubleshooting

Users

#The user object

#Create a user

#Retrieve a user

#Update a user

#Delete a user

#List all users