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

    Used for pre-filling Link's login screen. Provided when creating or patching the user object.

    If not provided, will be populated with identities data from connected accounts.

  • #
    last_namestring

    Used for pre-filling Link's login screen. Provided when creating or patching the user object.

    If not provided, will be populated with identities data from connected accounts.

  • #
    emailstring

    Used for pre-filling Link's login screen. Provided when creating or patching the user object.

    If not provided, will be populated with identities data from connected accounts.

  • #
    phone_numberstring

    Used for pre-filling Link's login screen. Provided when creating or patching the user object. E.164 international format.

    If not provided, will be populated with identities data from connected accounts.

  • #
    ssnstring

    Social Security number.

    Only used by banking reports.

  • #
    addressobject

    Only used by banking reports.

  • #
    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

    Only used by banking reports.

  • #
    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}
  • #
    external_metadataJSON
    optional

    Any valid JSON.

    Must be an object {} when used for banking reports.

  • #
    open_bankingobject
    optional

    Only 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.
  • #
    ssnstring
    optional

    Social Security number.

    Only required for banking reports.

  • #
    addressobject
    optional

    Only 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

    Only 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).
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}
  • #
    external_metadataJSON
    optional
    Any valid JSON.
  • #
    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]
Updating Argyle status...
© 2025 Argyle Systems Inc.argyle.com