>  Switch To Link 5 and API v2 Documentation

Users

Learn about the /users and /user-tokens endpoints.

#The user object

  • User objects represent distinct users that have connected their payroll accounts via Argyle Link.
  • You can list all users or retrieve a user by ID that you have saved in your database when one of the Argyle Link callbacks was invoked.
Attributes
  • #
    idstring (uuid)

    Unique ID of the user.

  • #
    created_atstring (datetime)

    Timestamp (ISO 8601) when the user object was created.

  • #
    employers_connectedarray of strings

    A list of names of employers that the user has connected to via Argyle Link. This list might be different from data_providers_connected, which can include payroll providers that service multiple employers (for example, MyADP). The connections might be active or previously connected employers, which are no longer active (for example, due to a user switching jobs).

    This field is populated after the initial scan is completed and the account is connected successfully, so there is a short (a few seconds) delay before you can see the list. Use employments webhooks to know when this data is available on the platform.

  • #
    data_providers_connectedarray of strings

    A list of the IDs of Link items that the user has connected. The connections might be active or previously connected Link items, which are no longer active (for example, due to a user switching jobs). This field is populated immediately after user creation.

  • #
    external_metadataJSON

    Typically used for grouping users or internal matching of Argyle user IDs. Can be added when creating or updating a user. Can be any valid JSON, such as a string or object.

    You can use the external_metadata field to classify users into categories as needed. We also recommend adding your internal user id's in external_metadata for easier tracking.

    When creating a user, include the metadata information as a body parameter: 

    1{
2    "external_metadata": {
3        "internalTracking_userId": "1324",
4        "internalTracking_groupClassification": "Gig Worker"
5    }
6}



Example
1{
2  "id": "0994b847-cc69-4d98-bc99-c5e65e762add",
3  "created_at": "2019-11-27T15:56:50.583233Z",
4  "employers_connected": [
5    "employerCo",
6    "rideCo"
7  ],
8  "data_providers_connected": [
9    "payrollCo",
10    "rideCo"
11  ],
12  "external_metadata": "User group A"
13}

#The user token object

  • User tokens are temporary access keys that ensure a user's permissions in Argyle Link are scoped to that specific user's data.
  • A new user token should be generated every time you are initializing Argyle Link for an existing user.
  • User tokens are JWT tokens with a short-lived expiry, and are explained in-depth in our Returning Users Guide.
Attributes
  • #
    accessstring

    Value passed when initializing Argyle Link for a returning user.

  • #
    refresh (*deprecated)string

    Value specific to JWT tokens.




Example
1{
2  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMzIxNDUsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzFkZjgzMGItOGJjYy00MDgyLTkxYzYtNjEwMTE0Njc3ODRhIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIiwidXNlcl9pZCI6IjAxODA1MTllLTYyMGYtYTQ4MC0wYTZkLTMwN2MwODZjMDc3MyJ9.qC0bQ0wFzVIp3I0a7BxjqrRha2Bexw5PycWIh1WQjTw",
3  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTMyMzIxNDUsImp0aSI6ImY4OWQ1NzkyLTcxZjYtNDM5ZS05NjZiLWVkY2M3ODYxODgwYSIsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIn0.Y1KilybzFeNbGEAjkxhJ-VeTZT9i7iTtRHSwDsnH5Bs"
4}

#Create a user

post/v1/users
  • Create a new user.
  • No payload is required for this request.
  • This request returns the new user's ID and an associated user token.

When creating a user, you have the option to attach external metadata to that user using the external_metadata object. This object can be used to attach any external information, such as a customer group identifier for grouping users.

If the external_metadata object is specified in the POST request, the API saves that information, but only returns the id and token fields. Metadata can also be updated with a PATCH request.

Request body
  • #
    external_metadataJSON
    optional

    Any valid JSON, such as a string or an object.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/users \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMjk2MDAsImlhdCI6MTY1MDYzNzYwMCwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzgyZjhlZDYtMzEwMy00YTZmLTgxOTMtZjdjN2JkMmEwMmVmIiwic3ViIjoiMDE4MDUxYWEtZjdhOS1hMGRiLTJmMzgtNmNmYTMyNWU5ZDY5IiwidXNlcl9pZCI6IjAxODA1MWFhLWY3YTktYTBkYi0yZjM4LTZjZmEzMjVlOWQ2OSJ9.U2i5ZOpHcooydnACMNGr1Ok-SmlCshhqCjKilQiXNkM",
3  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"
4}

#Retrieve a user and their metadata

get/v1/users/{id}

Retrieves a user object and any associated external_metadata of the specified user.

Path parameters
  • #
    idstring (uuid)
    required

    ID of the user object to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "0994b847-cc69-4d98-bc99-c5e65e762add",
3  "created_at": "2019-11-27T15:56:50.583233Z",
4  "employers_connected": [
5    "rideCo"
6  ],
7  "data_providers_connected": [
8    "rideCo"
9  ],
10  "external_metadata": {
11    "group_id": "Group A5"
12  }
13}

#Update a user's metadata

patch/v1/users/{id}
  • Update external metadata for an already existing user.
  • This request returns the user object with the updated external metadata.
Path parameters
  • #
    idstring (uuid)
    required

    ID of the user object, whose metadata should be updated.

Request body
  • #
    external_metadataJSON
    optional

    Any valid JSON, such as a string or object.

Example Request
1curl --request PATCH \
2     --url https://api.argyle.com/v1/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{"external_metadata": {}}'
Example Response
1{
2  "id": "0994b847-cc69-4d98-bc99-c5e65e762add",
3  "created_at": "2019-11-27T15:56:50.583233Z",
4  "employers_connected": [
5    "rideCo"
6  ],
7  "data_providers_connected": [
8    "rideCo"
9  ],
10  "external_metadata": {
11    "customer group": "lending"
12  }
13}

#List users

get/v1/users
  • List all users that are associated with your Link key.
  • This request returns an object with a results property that contains an array of up to limit user objects.
Query parameters
  • #
    limitinteger
    optional

    The number of user objects to be returned. The default is 10. Max value is 200.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/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": "2022-04-22T14:26:40.682437Z",
5    "data_providers_connected": [],
6    "employers_connected": [],
7    "external_metadata": {}
8  },
9  {
10    "id": "0180519e-620f-a480-0a6d-307c086c0773",
11    "created_at": "2022-04-22T14:12:55.951953Z",
12    "employers_connected": [
13      "employerCo",
14      "rideCo"
15    ],
16    "data_providers_connected": [
17      "payrollCo",
18      "rideCo"
19    ],
20    "external_metadata": {
21      "customer group": "lending"
22    }
23  }
24]

#Delete a user

delete/v1/users/{id}
  • Delete a user and all accounts associated with that user. In turn, all other resources—profiles, vehicles, documents, etc.—are deleted as well.
  • Use this endpoint to delete all information about a user. If you want to delete a single account of a given user, please refer to deleting an account.
  • When the user is successfully deleted, this request responds with a 204 status and an empty response body.

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/v1/users/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1"204 status code: No content."

#Create a user token

post/v1/user-tokens
  • Argyle utilizes JWT tokens as user tokens.
  • A new user token should be generated every time you are initializing Argyle Link for an existing user. User tokens are short-lived and will expire.
  • To create a user token, send a POST request with the request body containing a JSON object with the following format: {"user": "<id>"}.
  • This request returns a JSON object as its payload, consisting of an access token and refresh token. Only the access token is passed as the user token when initializing Argyle Link. Visit our creating user tokens guide for more information.
Request body
  • #
    userstring (uuid)
    required

    ID of the user object.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/user-tokens \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data {"user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"}
Example Response
1{
2  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMzIxNDUsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzFkZjgzMGItOGJjYy00MDgyLTkxYzYtNjEwMTE0Njc3ODRhIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIiwidXNlcl9pZCI6IjAxODA1MTllLTYyMGYtYTQ4MC0wYTZkLTMwN2MwODZjMDc3MyJ9.qC0bQ0wFzVIp3I0a7BxjqrRha2Bexw5PycWIh1WQjTw",
3  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTMyMzIxNDUsImp0aSI6ImY4OWQ1NzkyLTcxZjYtNDM5ZS05NjZiLWVkY2M3ODYxODgwYSIsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIn0.Y1KilybzFeNbGEAjkxhJ-VeTZT9i7iTtRHSwDsnH5Bs"
4}
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com