Create, query, update, and delete the child accounts of your dealer account. The same ones you manage in SW Portal › Clients (Clientes), from your code.
✓Before you start
- 1Get a Bearer Token using your SW username and password. We recommend using an infinite (non-expiring) token. All operations require it in the
Authorizationheader. - 2Create the child account with Create. The response returns its
idUser. - 3Update and Delete require that
userIdin the path. If you didn’t save it, retrieve it with Query.
💡 Important: to pause an account, use Activate/Deactivate. Delete removes the account and won’t go through if it still has stamps.
URLs
Select your active environment. The copy buttons and the code examples below are built with the base URL you choose here.
🛠️ Sandbox:
https://api.test.sw.com.mx
🚀 Production:
https://api.sw.com.mx
🔗 Endpoint
Four actions on child accounts. Pick one and its full reference is built below: endpoint, headers, parameters, example, and response.
Creates a child account from your dealer account, with its initial stamps. You can then manage it in SW Portal › Clients (Clientes).
POST/management/v2/api/dealers/users
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
name
string
REQUIRED
User’s name.
taxId
string
REQUIRED
User’s RFC.
email
string
REQUIRED
User’s email. It will be their username.
stamps
int
REQUIRED
Stamps to assign on creation.
isUnlimited
boolean
REQUIRED
Indicates whether the user will have unlimited stamps.
password
string
REQUIRED
User’s password. See the policies below.
notificationEmail
string
OPTIONAL
Email address for notifications.
phone
string
OPTIONAL
User’s phone number.
At least 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character
No whitespace
Different from the username
No symbols outside the accepted list
Returns the users linked to your token, paginated 10 per page. With no filters, it returns all your child accounts.
GET/management/v2/api/dealers/users
💡 All filters are optional and can be combined with &.
Property
Type
Usage
Description
TaxId
string
OPTIONAL
RFC linked to the user to query.
Email
string
OPTIONAL
Email of the user to query.
Name
string
OPTIONAL
Name of the user to query.
IdUser
guid
OPTIONAL
User’s GUID identifier.
IsActive
boolean
OPTIONAL
Filters active (true) or inactive (false) users.
Page
int
OPTIONAL
Page to retrieve. Defaults to 1.
PerPage
int
OPTIONAL
Records per page. Defaults to 10, max 50.
Filters the list by the RFC linked to the user.
GET/management/v2/api/dealers/users?TaxId=XIA190128J61
💡 All filters are optional and can be combined with &.
Property
Type
Usage
Description
TaxId
string
OPTIONAL
RFC linked to the user to query.
Email
string
OPTIONAL
Email of the user to query.
Name
string
OPTIONAL
Name of the user to query.
IdUser
guid
OPTIONAL
User’s GUID identifier.
IsActive
boolean
OPTIONAL
Filters active (true) or inactive (false) users.
Page
int
OPTIONAL
Page to retrieve. Defaults to 1.
PerPage
int
OPTIONAL
Records per page. Defaults to 10, max 50.
Returns a specific user by its GUID. Useful to check its status and balance before updating it.
GET/management/v2/api/dealers/users?IdUser=a8b8881a-3456-481b-96b9-e02fd895f5be
💡 All filters are optional and can be combined with &.
Property
Type
Usage
Description
TaxId
string
OPTIONAL
RFC linked to the user to query.
Email
string
OPTIONAL
Email of the user to query.
Name
string
OPTIONAL
Name of the user to query.
IdUser
guid
OPTIONAL
User’s GUID identifier.
IsActive
boolean
OPTIONAL
Filters active (true) or inactive (false) users.
Page
int
OPTIONAL
Page to retrieve. Defaults to 1.
PerPage
int
OPTIONAL
Records per page. Defaults to 10, max 50.
Combine filters with “&”. In the example: a specific email, only if the account is active.
GET/management/v2/api/dealers/users?Email=correo@example.com&IsActive=true
💡 All filters are optional and can be combined with &.
Property
Type
Usage
Description
TaxId
string
OPTIONAL
RFC linked to the user to query.
Email
string
OPTIONAL
Email of the user to query.
Name
string
OPTIONAL
Name of the user to query.
IdUser
guid
OPTIONAL
User’s GUID identifier.
IsActive
boolean
OPTIONAL
Filters active (true) or inactive (false) users.
Page
int
OPTIONAL
Page to retrieve. Defaults to 1.
PerPage
int
OPTIONAL
Records per page. Defaults to 10, max 50.
Updates a child account’s data: name, RFC, notification email, phone, or unlimited stamps.
PUT/management/v2/api/dealers/users/{userId}
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
userId
guid
REQUIRED
User ID. Get it with Query (idUser).
Property
Type
Usage
Description
iduser
guid
REQUIRED
ID of the user to update. Must match the one in the path.
name
string
OPTIONAL
New user name.
taxId
string
OPTIONAL
New user RFC.
notificationEmail
string
OPTIONAL
New notification email.
phone
string
OPTIONAL
New phone number.
isUnlimited
boolean
OPTIONAL
Indicates whether the user will have unlimited stamps.
Changes a child account’s password from your dealer account. No other data is modified.
PATCH/management/v2/api/dealers/users/{userId}/password
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
userId
guid
REQUIRED
User ID. Get it with Query (idUser).
Property
Type
Usage
Description
newPassword
string
REQUIRED
New password. It can’t be empty or reuse a previous one.
At least 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character
No whitespace
Different from the username
No symbols outside the accepted list
Activates or deactivates a child account. This is the recommended way to pause an account temporarily.
PATCH/management/v2/api/dealers/users/{userId}
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
userId
guid
REQUIRED
User ID. Get it with Query (idUser).
Property
Type
Usage
Description
isActive
boolean
REQUIRED
true to activate, false to deactivate.
Permanently deletes a child account you no longer need.
DELETE/management/v2/api/dealers/users/{userId}
Property
Type
Usage
Description
userId
guid
REQUIRED
User ID. Get it with Query (idUser).
Request Example
>
>
>
>
>
>
>
>
💡 Note: These examples are based on the SW SDKs, but you can call the REST API directly from any language you prefer.
Response
Property
Type
Description
status
string
Indicates the response status.
data
object | null
Data of the created user. Save idUser for the other operations.
Cause: The email already belongs to another user. The email works as the username, so it can’t be reused.
Solution: Use a different email. If the account already existed, find it with Query ?Email= and update it instead of creating it again.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
Property
Type
Description
status
string
Indicates the response status.
data
array | null
List of users. Each item contains a registered user’s data.
meta
object | null
Pagination: current page, records per page, and totals.
links
object | null
Self, First, and End paths to navigate between pages.
Cause: A filter has an invalid format. The most common case is an IdUser that isn’t a complete GUID.
Solution: Send IdUser with all 36 characters (32 digits and 4 hyphens), and URL-encode values with spaces or symbols, such as Name or Email.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
messageDetail
string
Additional error detail, when available.
Property
Type
Description
status
string
Indicates the response status.
data
array | null
List of users. Each item contains a registered user’s data.
meta
object | null
Pagination: current page, records per page, and totals.
links
object | null
Self, First, and End paths to navigate between pages.
Cause: A filter has an invalid format. The most common case is an IdUser that isn’t a complete GUID.
Solution: Send IdUser with all 36 characters (32 digits and 4 hyphens), and URL-encode values with spaces or symbols, such as Name or Email.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
messageDetail
string
Additional error detail, when available.
Property
Type
Description
status
string
Indicates the response status.
data
array | null
List of users. Each item contains a registered user’s data.
meta
object | null
Pagination: current page, records per page, and totals.
links
object | null
Self, First, and End paths to navigate between pages.
Cause: A filter has an invalid format. The most common case is an IdUser that isn’t a complete GUID.
Solution: Send IdUser with all 36 characters (32 digits and 4 hyphens), and URL-encode values with spaces or symbols, such as Name or Email.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
messageDetail
string
Additional error detail, when available.
Property
Type
Description
status
string
Indicates the response status.
data
array | null
List of users. Each item contains a registered user’s data.
meta
object | null
Pagination: current page, records per page, and totals.
links
object | null
Self, First, and End paths to navigate between pages.
Cause: A filter has an invalid format. The most common case is an IdUser that isn’t a complete GUID.
Solution: Send IdUser with all 36 characters (32 digits and 4 hyphens), and URL-encode values with spaces or symbols, such as Name or Email.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
messageDetail
string
Additional error detail, when available.
Property
Type
Description
status
string
Indicates the response status.
data
string
UUID of the updated user.
Cause: All the values sent are the same as the user’s current ones: there’s nothing to change.
Solution: Send only the properties that change and leave the rest as null. Query the user by ID to compare its current values.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
Property
Type
Description
status
string
Indicates the response status.
data
string | null
Request confirmation.
Cause: The new password has already been used on that account.
Solution: Create a new password that meets the policies: uppercase, lowercase, number, symbol, and at least 8 characters.
Property
Type
Description
status
string
Indicates the response status.
Property
Type
Description
status
string
Indicates the response status.
data
object | null
Data of the activated or deactivated user.
Cause: The request arrived without a body, or without the Content-Type: application/json header.
Solution: Send the JSON {“isActive”: true|false} with the Content-Type: application/json header.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
Cause: The account still has stamps assigned.
Solution: Remove the stamps with the Balance API V2 before deleting, or deactivate the account instead.
Property
Type
Description
status
string
Indicates the response status.
message
string
Only present in error responses. Describes the reason for the error.
In SW® we strive to be the best for You, which is why your opinion is very important. Please help us by rating this article and leaving your comments.