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:
- After sending an invite, a user invite object will be returned in the response.
- Save the invite
id
from the user invite object. You can also list all invites and filter for the relevant user if the inviteid
was not originally saved. - (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. - 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
- #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.
- #page_headingstring
The
heading 1
of the landing page. - #page_descriptionstring
The text content of the landing page.
- #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.
- #reply_tostring
The reply email address for your user invite.
- #customization_idstring
Argyle Link customization ID, found or created through Flows in Console.
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
- #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 userid
), but no accounts have been successfully connected.completed
- User submitted login credentials in Argyle Link (creating a userid
), 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.
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
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.
- #namestringrequired
The name of the template. Each name must be unique.
- #email_bodystringrequired
The text content of the email to be sent as part of the invitation.
- #sms_bodystringrequired
The text message content to be sent as part of the invitation.
- #headerstringrequired
The title header of the invitation email.
- #subjectstringrequired
The email subject of the invitation email.
- #senderstringrequired
The
From
field of the invitation email. - #companystringrequired
The company name to be displayed when using the [Sender] placeholder.
- #logo_urlstringrequired
A link to the logo to be used in the invitation email.
- #page_headingstringrequired
The
heading 1
of the landing page. - #page_descriptionstringrequired
The text content of the landing page.
- #page_configobjectoptional
Configuration parameters for the success page.
- #page_success_headingstringrequired
The
heading 1
of the success page. - #page_success_descriptionstringrequired
The text content of the success page.
- #reply_tostringoptional
The reply to email address.
- #customization_idstringoptional
Argyle Link customization ID, found or created through Flows in Console.
Must be the ID of an embedded experience.
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 }'
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
Retrieve a user invite template object with the supplied ID, and returns a user invite template object if a valid identifier was provided.
- #idstring (uuid)required
The identifier of the user invite template to be retrieved.
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'
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
Returns a list of existing templates.
- #limitintegeroptional
The number of user invite template objects to be returned. The default is 10. Max value is 200.
1curl --request GET \
2 --url https://api.argyle.com/v1/user-invite-templates \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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
Deletes a user invite template.
When a user invite template is successfully deleted, the request returns a 200 status and an empty response body.
- #idstring (uuid)required
ID of the user invite template to be deleted.
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'
1"200 status code: No content."
#Send an invite
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.
- #invite_template_idstring (uuid)required
ID of the user invite template that should be applied to the invite.
- #full_namestringrequired
The full name of the user.
- #phone_numberstringoptional
The phone number of the user. Optional, but at least one of
email
andphone_number
is required. - #emailstringoptional
The email address of the user. Optional, but you must include either
email
andphone_number
. - #pds_configobjectoptional
Add your unencrypted DDS configuration object to enable a direct deposit switching flow.
- #customization_idstringoptional
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.
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 }'
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
Resend a previously sent-out invite.
This request returns the user invite object with status
= sent
and an updated invited_at
time.
- #idstring (uuid)required
ID of the invite to be resent.
1curl --request POST \
2 --url https://api.argyle.com/v1/user-invites/{id} \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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
Invalidate a previously sent-out invite.
This request returns the user invite object with status
= revoked
and a revoked_at
time.
- #idstring (uuid)required
ID of the invite to be revoked.
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'
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
Retrieve a user invite object with the supplied ID.
This request returns a user invite object if a valid identifier was provided.
- #idstring (uuid)required
The identifier of the user invite to be retrieved.
1curl --request GET \
2 --url https://api.argyle.com/v1/user-invites/{id} \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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
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.
- #limitintegeroptional
The number of user invite objects to be returned. The default is 10. Max value is 200.
1curl --request GET \
2 --url https://api.argyle.com/v1/user-invites \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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]