>  Switch To Link 5 and API v2 Documentation

User invites

Learn about the /user-invite-templates and /user-invites endpoints.

Overview#

You can send invites to new users containing a link they can click to connect their payroll accounts through Argyle. Invites can be sent via Console or using the API method below. User invites are created using the /user-invite-templates endpoint and sent using the /user-invites endpoint and can be sent via SMS, email, or both.

  • Both SMS and email fields must be included in user invite templates
  • You can choose whether to send an SMS, email, or both when sending an invite

Creating an invite template will generate a unique id which can be used as the invite-template-id when sending an invite. This invite-template-id contains your messaging, landing page, and Argyle Link customizations. Once an invite is sent, a user invite object will be created.

Returning users#

User invites can be re-used for the same user. This allows the user to return to Argyle Link, enabling them to:

  • Re-verify disconnected accounts
  • Connect additional accounts
  • Revoke access to previously connected accounts

Follow the steps below to allow a user to return to Argyle Link through user invites:

  1. After sending an invite, a user invite object will be returned in the response.
  2. Save the invite id from the user invite object. You can also list all invites and filter for the relevant user if the invite id was not originally saved.
  3. (Optional) When an invite is first sent, a new user object that represents this new user is created. If you want to update the user's metadata (often used for internal ID matching), save the ID value returned in the user field of the user invite object, and use this ID to update the user's metadata.
  4. Resend the invite using the invite id, and the user will be able to return to Argyle Link to take additional action.

You can also manually retrieve and send the original invite URL through Console, which allows the user to reconnect to Argyle Link as well.

Tracking invite status#

  • Retrieve the invite sent to the user. The status field of the user invite object will indicate where the invited user is in the connection process.
  • Use accounts webhooks to automatically be notified when a user submits login credentials, and whether they successfully connect a payroll account.

Adding deposit switching#

Add your unencrypted DDS configuration in the pds_config body parameter when sending the invite.

#The user invite template object

Attributes
  • #
    idstring (uuid)

    Unique ID of the template.

  • #
    namestring

    The name of the template.

  • #
    companystring

    Your company/brand name that is shown to users in the invite.

  • #
    logo_urlstring

    A link to the logo to be used in the invitation email. Logo dimensions: 120x120 px

  • #
    sms_bodystring

    The text message content to be sent as part of the invitation.


  • #
    senderstring

    The "From" field of the invitation email.


  • #
    subjectstring

    The email subject of the invitation email.

  • #
    headerstring

    The title header of the invitation email.

  • #
    email_bodystring

    The text content of the invitation email.

  • #
    buttonstring

    The call-to-action button label within the email.

  • #
    page_headingstring

    The heading 1 of the landing page.


  • #
    page_descriptionstring

    The text content of the landing page.

  • #
    page_buttonstring

    The call-to-action button label on the landing page to initiate Argyle Link.

  • #
    page_configobject

    Configuration parameters for the success page.

  • #
    page_success_headingstring

    The heading 1 of the success page.

  • #
    page_success_descriptionstring

    The text content of the success page.

  • #
    page_success_show_buttonboolean

    The text content of the success page.

  • #
    page_success_buttonstring

    The call-to-action button label on the success page.

  • #
    reply_tostring

    The reply email address for your user invite.

  • #
    customization_idstring

    Argyle Link customization ID, found or created through Flows in Console.



Example
1{
2  "id": "9f82994c-774d-11eb-b1c7-13e87316bacb",
3  "name": "regular",
4  "company": "GoodLoans",
5  "logo_url": "https://company.com/logo.jpg",
6  "sms_body": "[Company] has asked you to connect your employment account. Get started here: [Link]",
7  "sender": "[Company]",
8  "subject": "Connect Your Employment Account",
9  "header": "[Company] is requesting you to connect your employment account",
10  "email_body": "Hi, [Name]\n\n[Company] is working with a 3rd party to verify your work history. It's a quick process that should not take longer than a few minutes to complete. Get started by clicking the link below.\n\nSincerely,\n[Sender]",
11  "button": "Connect your employment account",
12  "page_heading": "Let's connect your employment account",
13  "page_description": "[Company] has asked you to connect your employment account to use their services.",
14  "page_button": "Connect Account",
15  "page_config": {
16    "page_success_heading": "Thank you for connecting your accounts",
17    "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
18    "page_success_button": "Connect Account",
19    "page_success_show_button": true
20  },
21  "reply_to": "[email protected]",
22  "customization_id": "5UBR4EJ8"
23}

#The user invite object

Attributes
  • #
    idstring (uuid)

    A unique ID for the invite.

  • #
    userstring (uuid)

    The user ID associated with this invite. It is available only when a user has accepted the invite and successfully connected via Argyle Link.

  • #
    user_tokenstring (uuid)

    A unique token generated by Argyle Link. Only available when a user has attempted to connect via Argyle Link. Used to restore the session when the user comes back for a second time to update their information.

  • #
    full_namestring

    The full name of the user.

  • #
    emailstring

    The email address which received the invite.

  • #
    phone_numberstring

    The phone number which received the invite.

  • #
    invited_atstring

    Denotes the time when the invitation was sent out. This field is updated if you resend an invite. Timestamps follow the ISO 8601 standard.

  • #
    invite_template_idstring (uuid)

    ID of the user invite template that was used to send the invite.

  • #
    statusstring (enum)

    The status of the invitation. Possible values:


    sent - Invite successfully sent.


    initiated - User has clicked the invite URL, but has not submitted credentials, uploaded documents, or completed a "Can't find your income source?" form.


    attempted - User submitted login credentials in Argyle Link (creating a user id), but no accounts have been successfully connected.


    completed - User submitted login credentials in Argyle Link (creating a user id), and at least one account has been successfully connected (uploading documents and form submissions are considered a successful connection).


    revoked - Invite has been revoked (invite URL is disabled).

  • #
    revoked_atstring

    Denotes when the invite was revoked. Timestamps follow the ISO 8601 standard.

  • #
    urlstring

    The invite URL sent to the user.




Example
1{
2  "id": "317e7736-7761-11eb-b642-238b63a89ff2",
3  "user": "8a5f613a-673a-4434-aeee-1a38b960b936",
4  "user_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjE2ODQ3MzA1LCJqdGkiOiI1NzA2ZjM5MTEzMzk0ZDM1YTA5MWVjYzgxNjc3NjdjNCIsInVzZXJfaWQiOiI4YTVmNjEzYS02NzNhLTQ0MzQtYWVlZS0xYTM4Yjk2MGI5MzYiLCJjbGllbnRfaWQiOiJjMDIwYjNjMy0zY2Q5LTRmY2YtYjg1OC0xMzlkZWU2NmU2ZjMifQ.9CzhA-Gx9QqBManrogEbgHuKduVWvtC9OGxDe_RTgl8",
5  "email": "[email protected]",
6  "phone_number": "+12025550104",
7  "full_name": "John Smith",
8  "invited_at": "2021-02-25T12:01:29.083Z",
9  "invite_template_id": "315e0d98-7761-11eb-b642-c7dfaaf3c8cf",
10  "revoked_at": null,
11  "status": "completed",
12  "url": "https://console.argyle.com/add-work-accounts/ab2254e8-60a6-12ed-cb32-d4fad896515b"
13}

#Create an invite template

post/v1/user-invite-templates

Create a new invite template with the provided attributes.

These placeholders can be used in the text contents. Each placeholder can be replaced by these values:

  • [Company] - Corresponds to the company attribute in the user invite template object.
  • [Name] - Corresponds to the full_name attribute in the user invite template object.
  • [Link] - Shortened link to accept the invitation.
  • [Sender] - Corresponds to the sender attribute in the user invite template object.

This request returns a unique template id and all your provided template attributes.

Request body
  • #
    namestring
    required

    The name of the template. Each name must be unique.

  • #
    email_bodystring
    required

    The text content of the email to be sent as part of the invitation.

  • #
    sms_bodystring
    required

    The text message content to be sent as part of the invitation.

  • #
    headerstring
    required

    The title header of the invitation email.

  • #
    buttonstring
    required

    The call-to-action button label within the email.

  • #
    subjectstring
    required

    The email subject of the invitation email.

  • #
    senderstring
    required

    The From field of the invitation email.

  • #
    companystring
    required

    The company name to be displayed when using the [Sender] placeholder.

  • #
    logo_urlstring
    required

    A link to the logo to be used in the invitation email.

  • #
    page_headingstring
    required

    The heading 1 of the landing page.

  • #
    page_descriptionstring
    required

    The text content of the landing page.

  • #
    page_buttonstring
    required

    The call-to-action button label on the landing page to initiate Argyle Link.

  • #
    page_configobject
    optional

    Configuration parameters for the success page.

  • #
    page_success_headingstring
    required

    The heading 1 of the success page.

  • #
    page_success_descriptionstring
    required

    The text content of the success page.

  • #
    page_success_show_buttonboolean
    required

    Denotes if the action button on the success page is shown.


    If true, the page_success_button is required.

  • #
    page_success_buttonstring
    optional

    The call-to-action button label on the success page.

  • #
    reply_tostring
    optional

    The reply to email address.

  • #
    customization_idstring
    optional

    Argyle Link customization ID, found or created through Flows in Console.

    Must be the ID of an embedded experience.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/user-invite-templates \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "name": "test name",
7        "email_body": "Hi, [Name], [Company] is working with a 3rd party to verify your work history. It’s a quick process that should not take longer than a few minutes to complete. Get started by clicking the link below. Sincerely, [Sender]",
8        "sms_body": "[Company] has asked you to connect your employment account. Get started here: [Link]",
9        "header": "[Company] is requesting you to connect your employment account",
10        "button": "Connect your employment account",
11        "subject": "Connect Your Employment Account",
12        "sender": "[Company]",
13        "company": "Test Company",
14        "logo_url": "https://company.com/logo.jpg",
15        "page_heading": "Please connect your employment account",
16        "page_description": "[Company] has asked you to connect your employment account to use their services.",
17        "page_button": "Connect Account",
18        "page_config": {
19          "page_success_heading": "Thank you for connecting your accounts",
20          "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
21          "page_success_show_button": true,
22          "page_success_button": "Connect Account"
23        },
24        "reply_to": "[email protected]",
25        "customization_id": "00000000"
26     }'
Example Response
1{
2  "id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
3  "name": "regular",
4  "email_body": "Hi, [Name]\n\n[Company] is working with a 3rd party to verify your work history. It's a quick process that should not take longer than a few minutes to complete. Get started by clicking the link below.\n\nSincerely,\n[Sender]",
5  "sms_body": "[Company] has asked you to connect your employment account. Get started here: [Link]",
6  "button": "Connect your employment account",
7  "header": "[Company] is requesting you to connect your employment account",
8  "subject": "Connect Your Employment Account",
9  "sender": "[Company]",
10  "company": "GoodLoans",
11  "logo_url": "https://company.com/logo.jpg",
12  "page_heading": "Let's connect your employment account",
13  "page_description": "[Company] has asked you to connect your employment account to use their services.",
14  "page_button": "Connect Account",
15  "page_config": {
16    "page_success_heading": "Thank you for connecting your accounts",
17    "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
18    "page_success_show_button": true,
19    "page_success_button": "Continue"
20  },
21  "reply_to": null,
22  "customization_id": null
23}

#Retrieve a template

get/v1/user-invite-templates/{id}

Retrieve a user invite template object with the supplied ID, and returns a user invite template object if a valid identifier was provided.

Path parameters
  • #
    idstring (uuid)
    required

    The identifier of the user invite template to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/user-invite-templates/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
3  "name": "regular",
4  "email_body": "Hi, [Name]\n\n[Company] is working with a 3rd party to verify your work history. It's a quick process that should not take longer than a few minutes to complete. Get started by clicking the link below.\n\nSincerely,\n[Sender]",
5  "sms_body": "[Company] has asked you to connect your employment account. Get started here: [Link]",
6  "button": "Connect your employment account",
7  "header": "[Company] is requesting you to connect your employment account",
8  "subject": "Connect Your Employment Account",
9  "sender": "[Company]",
10  "company": "GoodLoans",
11  "logo_url": "https://company.com/logo.jpg",
12  "page_heading": "Let's connect your employment account",
13  "page_description": "[Company] has asked you to connect your employment account to use their services.",
14  "page_button": "Connect Account",
15  "page_config": {
16    "page_success_heading": "Thank you for connecting your accounts",
17    "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
18    "page_success_show_button": true,
19    "page_success_button": "Connect Account"
20  },
21  "reply_to": "[email protected]",
22  "customization_id": "2BLR1EJ6"
23}

#List templates

get/v1/user-invite-templates/{id}

Returns a list of existing templates.

Query parameters
  • #
    limitinteger
    optional

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

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/user-invite-templates \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1[
2  {
3    "id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
4    "name": "regular",
5    "email_body": "Hi, [Name]\n\n[Company] is working with a 3rd party to verify your work history. It's a quick process that should not take longer than a few minutes to complete. Get started by clicking the link below.\n\nSincerely,\n[Sender]",
6    "sms_body": "[Company] has asked you to connect your employment account. Get started here: [Link]",
7    "button": "Connect your employment account",
8    "header": "[Company] is requesting you to connect your employment account",
9    "subject": "Connect Your Employment Account",
10    "sender": "[Company]",
11    "company": "GoodLoans",
12    "logo_url": "https://company.com/logo.jpg",
13    "page_heading": "Let's connect your employment account",
14    "page_description": "[Company] has asked you to connect your employment account to use their services.",
15    "page_button": "Connect Account",
16    "page_config": {
17      "page_success_heading": "Thank you for connecting your accounts",
18      "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
19      "page_success_show_button": true,
20      "page_success_button": "Connect Account"
21    },
22    "reply_to": null,
23    "customization_id": "3RHE2QY8"
24  },
25  {
26    "id": "f8d8b90a-e678-11eb-a6d1-83071453d4b3",
27    "name": "verification",
28    "email_body": "Hi, [Name] \n\nAs part of your application [Company] is requesting to run a work & income verification report. It's a quick process and both you and [Company] will receive a copy of the report.",
29    "sms_body": "[Company] has asked you to link your income sources. Get started here: [Link]",
30    "button": "Start Verification",
31    "header": "[Company] is requesting to run a work & income verification",
32    "subject": "Work & Income Verification Requested",
33    "sender": "[Company]",
34    "company": "Argyle",
35    "logo_url": "https://res.cloudinary.com/argyle-media/image/upload/w_200,h_200,c_fill,q_100/v1604512727/client-logos/0d9b5bf3-97fa-4757-a136-b2a03d171414",
36    "page_heading": "Let's connect your work accounts",
37    "page_description": "[Company] has asked you to link the companies you make money from as part of their service.",
38    "page_button": "Connect accounts",
39    "page_config": {
40      "page_success_heading": "Thank you for connecting your accounts",
41      "page_success_description": "You are all set. If you have any questions please reach out to [Company]",
42      "page_success_show_button": true,
43      "page_success_button": "Connect another account"
44    },
45    "reply_to": "[email protected]",
46    "customization_id": null
47  }
48]

#Delete a template

delete/v1/user-invite-templates/{id}

Deletes a user invite template.

When a user invite template is successfully deleted, the request returns a 200 status and an empty response body.

Path parameters
  • #
    idstring (uuid)
    required

    ID of the user invite template to be deleted.

Example Request
1curl --request DELETE \
2     --url https://api.argyle.com/v1/user-invite-templates/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1"200 status code: No content."

#Send an invite

post/v1/user-invites

Send out an invite to a user's email and/or phone. If both email and phone_number are provided, then both an email and a text message will be sent. If only one of them is provided, then only the corresponding action will be executed.

This request returns the user invite object with status = sent.

Request body
  • #
    invite_template_idstring (uuid)
    required

    ID of the user invite template that should be applied to the invite.

  • #
    full_namestring
    required

    The full name of the user.

  • #
    phone_numberstring
    optional

    The phone number of the user. Optional, but at least one of email and phone_number is required.

  • #
    emailstring
    optional

    The email address of the user. Optional, but you must include either email and phone_number.

  • #
    pds_configobject
    optional

    Add your unencrypted DDS configuration object to enable a direct deposit switching flow.

  • #
    customization_idstring
    optional

    Argyle Link customization ID, found or created through Flows in Console.

    Will not override any optional customization_id included in the invite template. Must be the ID of an embedded experience.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/user-invites \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
7        "full_name": "John Smith",
8        "email": "[email protected]"
9     }'
Example Response
1{
2  "id": "3e9efffc-c252-11ec-98ee-1bc6fa2df55d",
3  "user": null,
4  "user_token": null,
5  "email": "[email protected]",
6  "phone_number": null,
7  "full_name": "John Smith",
8  "invited_at": "2022-04-22T15:38:23.534Z",
9  "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
10  "revoked_at": null,
11  "status": "sent",
12  "url": "https://console.argyle.com/add-work-accounts/ab2254e8-60a6-12ed-cb32-d4fad896515b"
13}

#Resend an invite

post/v1/user-invites/{id}

Resend a previously sent-out invite.

This request returns the user invite object with status = sent and an updated invited_at time.

Path parameters
  • #
    idstring (uuid)
    required

    ID of the invite to be resent.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/user-invites/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "3e9efffc-c252-11ec-98ee-1bc6fa2df55d",
3  "user": null,
4  "user_token": null,
5  "email": "[email protected]",
6  "phone_number": null,
7  "full_name": "John Smith",
8  "invited_at": "2022-05-22T15:39:35.388Z",
9  "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
10  "revoked_at": null,
11  "status": "sent",
12  "url": "https://console.argyle.com/add-work-accounts/ab2254e8-60a6-12ed-cb32-d4fad896515b"
13}

#Revoke an invite

post/v1/user-invites/{id}/revoke

Invalidate a previously sent-out invite.

This request returns the user invite object with status = revoked and a revoked_at time.

Path parameters
  • #
    idstring (uuid)
    required

    ID of the invite to be revoked.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/user-invites/{id}/revoke \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "3e9efffc-c252-11ec-98ee-1bc6fa2df55d",
3  "user": null,
4  "user_token": null,
5  "email": "[email protected]",
6  "phone_number": null,
7  "full_name": "John Smith",
8  "invited_at": "2022-04-22T15:39:35.388Z",
9  "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
10  "revoked_at": "2022-05-22T15:40:16.138Z",
11  "status": "revoked",
12  "url": "https://console.argyle.com/add-work-accounts/ab2254e8-60a6-12ed-cb32-d4fad896515b"
13}

#Retrieve an invite

get/v1/user-invites/{id}

Retrieve a user invite object with the supplied ID.

This request returns a user invite object if a valid identifier was provided.

Path parameters
  • #
    idstring (uuid)
    required

    The identifier of the user invite to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/user-invites/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "c8c23f78-c252-11ec-8472-9f9d9a6cf2e7",
3  "user": null,
4  "user_token": null,
5  "email": "[email protected]",
6  "phone_number": null,
7  "full_name": "John Smith",
8  "invited_at": "2022-04-22T15:43:08.804Z",
9  "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
10  "revoked_at": null,
11  "status": "sent",
12  "url": "https://console.argyle.com/add-work-accounts/ab2254e8-60a6-12ed-cb32-d4fad896515b"
13}

#List invites

get/v1/user-invites

Return a list of all sent-out invites.

This request returns an object with a results property that contains an array of up to limit user invite objects.

Query parameters
  • #
    limitinteger
    optional

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

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/user-invites \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1[
2  {
3    "id": "c8c23f78-c252-11ec-8472-9f9d9a6cf2e7",
4    "user": null,
5    "user_token": null,
6    "email": "[email protected]",
7    "phone_number": null,
8    "full_name": "John Smith",
9    "invited_at": "2022-04-22T15:43:08.804Z",
10    "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
11    "revoked_at": null,
12    "status": "sent",
13    "url": "https://console.argyle.com/add-work-accounts/ac2254e8-60a6-12ed-cb32-d4fad896515b"
14  },
15  {
16    "id": "3e9efffc-c252-11ec-98ee-1bc6fa2df55d",
17    "user": null,
18    "user_token": null,
19    "email": "[email protected]",
20    "phone_number": null,
21    "full_name": "John Smith",
22    "invited_at": "2022-04-22T15:41:50.257Z",
23    "invite_template_id": "c7ee8f30-b253-11eb-9ce1-bf8bb5082eb7",
24    "revoked_at": "2022-04-22T15:40:16.138Z",
25    "status": "revoked",
26    "url": "https://console.argyle.com/add-work-accounts/ad2254e8-60a6-12ed-cb32-d4fad896515b"
27  }
28]
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com