API Resource: Users

Jeff Wigal
  • Updated
Follow

Assignr API - Version 1 Deprecation

This page describes version 1 of the Assignr API, which will be discontinued on May 31, 2022. 

The current version of the Assignr API is version 2. Documentation can be found at our official API documentation site. To obtain access to version 2 of the API, please contact us. 

Data Elements

Name Read Only Required Type Length Notes
id Yes   Number    
first_name   Yes String 90  
mi     String 90  
last_name   Yes String 90  
street1     String 90  
street2     String 90  
city     String 90  
state     String 90  
postal     String 90  
home_phone     String 90  
work_phone     String 90  
mobile_phone     String 90  
email     String 100  
email2     String 100  
grade     String 90  
lock_version     Number    
created_at Yes   String   RFC-822 Date Format, local time zone
updated_at Yes   String   RFC-822 Date Format, local time zone
is_assignor     Number   0 or 1 (Default is 0)
is_referee     Number   0 or 1 (Default is 1)
is_observer     Number   0 or 1 (Default is 0)
is_manager     Number   0 or 1 (Default is 0)
manager_role_name     String   Can only be populated with users who have the Manager permission
login     String 90  
password **   String 90  
password_confirmation **   String 90  
send_authorization_email **   String 90  

Notes

  • password, password_confirmation, and send_authorization_email fields are not displayed in the returned data.
  • To set a password, set the password and password_confirmation fields.
  • To send a signup email, or reset a password, pass ‘Y’ to the send_authorization_email field. This is the most secure way to send credentials to a referee.

Validations

  • Each referee must have a unique first and last name, with respect to other referees within a site.
  • email and email2 must be a properly formatted email address, if they are provided.
  • Users must be assigned the referee role in order to be assigned to a game, or to be able to use any of the referee-specific attributes (conflicts, availability, and ability).
  • Most sites have a maximum number of referees that can be in the system at a time. A user with the referee role cannot be created if the site has reached it’s plan limit.

Retrieve a list of users (INDEX)

Return a paginated list of users. Limit is 50 users per request. 

Sample Response: GET /users.xml

<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user>
    <id>7294</id>
    <first_name>Derick</first_name>
    <mi>A</mi>
    <last_name>Altenwerth</last_name>
    <street1>5486 Charity Via</street1>
    <street2>Langtown School</street2>
    <city>Port Tyreeland</city>
    <state>SC</state>
    <postal>46460</postal>
    <home_phone>541.885.7680</home_phone>
    <work_phone>(272)015-7299</work_phone>
    <mobile_phone>061-086-7246 x4038</mobile_phone>
    <email>lempi.renner@framiwelch.uk</email>
    <email2>leslie_fay@jerdewilkinson.name</email2>
    <grade>USSF 8</grade>
    <lock_version>6</lock_version>
    <created_at>2010-04-03 21:30:02 -0400</created_at>
    <updated_at>2012-03-16 16:13:10 -0400</updated_at>
    <is_assignor>0</is_assignor>
    <is_referee>1</is_referee>
    <is_observer>0</is_observer>
            <is_manager>0</is_manager>
  </user>
  <user>
    <id>7292</id>
    <first_name>Camryn</first_name>
    <mi>K</mi>
    <last_name>Anderson</last_name>
    <street1>78158 Wanda Curve</street1>
    <street2>Feilborough Park</street2>
    <city>West Elishafurt</city>
    <state>DE</state>
    <postal>43962-1766</postal>
    <home_phone>1-628-628-0515 x11951</home_phone>
    <work_phone>1-213-356-7512</work_phone>
    <mobile_phone>177-108-6720</mobile_phone>
    <email>lavon.hoppe@bartell.ca</email>
    <email2>earnest@kosstorp.co.uk</email2>
    <grade>USSF 8</grade>
    <lock_version>6</lock_version>
    <created_at>2010-04-03 21:30:02 -0400</created_at>
    <updated_at>2012-03-16 16:13:10 -0400</updated_at>
    <is_assignor>0</is_assignor>
    <is_referee>1</is_referee>
    <is_observer>0</is_observer>
            <is_manager>0</is_manager>
            <manager_role_name></manager_role_name>
  </user>
  <!--  repeat for up to 50 in this list -->
  <page>1</page>
  <pages>2</pages>
  <count>65</count>
</users>

Sample Response: GET /users.json

{
    "page":1,
    "pages":2,
    "count":65,
    "users":
    [
        {
            "id":7294,
            "first_name":"Derick",
            "mi":"A",
            "last_name":"Altenwerth",
            "street1":"5486 Charity Via",
            "street2":"Langtown School",
            "city":"Port Tyreeland",
            "state":"SC",
            "postal":"46460",
            "home_phone":"541.885.7680",
            "work_phone":"(272)015-7299",
            "mobile_phone":"061-086-7246",
            "email":"lempi.renner@framiwelch.uk",
            "email2":"leslie_fay@jerdewilkinson.name",
            "grade":"USSF 8",
            "lock_version":6,
            "created_at":"Sat, 03 Apr 2010 21:30:02 -0400",
            "updated_at":"Fri, 16 Mar 2012 16:13:10 -0400",
                            "manager_role_name": null,
            "is_assignor":0,
            "is_referee":1,
            "is_observer":0,
                            "is_manager":0
        },
        {
            "id":7292,
            "first_name":"Camryn",
            "mi":"K",
            "last_name":"Anderson",
            "street1":"78158 Wanda Curve",
            "street2":"Feilborough Park",
            "city":"West Elishafurt",
            "state":"DE",
            "postal":"43962-1766",
            "home_phone":"1-628-628-0515",
            "work_phone":"1-213-356-7512",
            "mobile_phone":"177-108-6720",
            "email":"lavon.hoppe@bartell.ca",
            "email2":"earnest@kosstorp.co.uk",
            "grade":"USSF 8",
            "lock_version":6,
            "created_at":"Sat, 03 Apr 2010 21:30:02 -0400",
            "updated_at":"Fri, 16 Mar 2012 16:13:10 -0400",
                            "manager_role_name": null,
            "is_assignor":0,
            "is_referee":1,
            "is_observer":0,
                            "is_manager":0
        },
        {
            "id":7310,
            "first_name":"Nathanael",
            "mi":"C",
            "last_name":"Ankunding",
            "street1":"52105 Rick Ridge",
            "street2":"Lake Andreanne School",
            "city":"South Hillary",
            "state":"HI",
            "postal":"80303-6122",
            "home_phone":"535-642-0549",
            "work_phone":"(168)211-4584",
            "mobile_phone":"722.235.4899",
            "email":"ashly_mosciski@kilback.name",
            "email2":"irving@corkerylang.us",
            "grade":"USSF 8",
            "lock_version":6,
            "created_at":"Sat, 03 Apr 2010 21:30:05 -0400",
            "updated_at":"Fri, 16 Mar 2012 16:13:10 -0400",
                            "manager_role_name": null,
            "is_assignor":0,
            "is_referee":1,
            "is_observer":0,
                            "is_manager":0
        },
        ... repeat for up to 50 in this list ...
    ]
}

Retrieve a specific user (SHOW)

The following commands will retrieve the user details for a specific user.

Sample Response: GET /users/123.xml

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id>7294</id>
  <first_name>Derick</first_name>
  <mi>A</mi>
  <last_name>Altenwerth</last_name>
  <street1>5486 Charity Via</street1>
  <street2>Langtown School</street2>
  <city>Port Tyreeland</city>
  <state>SC</state>
  <postal>46460</postal>
  <home_phone>541.885.7680</home_phone>
  <work_phone>(272)015-7299</work_phone>
  <mobile_phone>061-086-7246 x4038</mobile_phone>
  <email>lempi.renner@framiwelch.uk</email>
  <email2>leslie_fay@jerdewilkinson.name</email2>
  <grade>USSF 8</grade>
  <lock_version>6</lock_version>
  <created_at>2010-04-03 21:30:02 -0400</created_at>
  <updated_at>2012-03-16 16:13:10 -0400</updated_at>
  <is_assignor>0</is_assignor>
  <is_referee>1</is_referee>
  <is_observer>0</is_observer>
        <is_manager>0</is_manager>
        <manager_role_name></manager_role_name>
</user>

Sample Response: GET /users/123.json

{
    "user":
    {
        "id":7294,
        "first_name":"Derick",
        "mi":"A",
        "last_name":"Altenwerth",
        "street1":"5486 Charity Via",
        "street2":"Langtown School",
        "city":"Port Tyreeland",
        "state":"SC",
        "postal":"46460",
        "home_phone":"541.885.7680",
        "work_phone":"(272)015-7299",
        "mobile_phone":"061-086-7246 x4038",
        "email":"lempi.renner@framiwelch.uk",
        "email2":"leslie_fay@jerdewilkinson.name",
        "grade":"USSF 8",
        "lock_version":6,
        "created_at":"Sat, 03 Apr 2010 21:30:02 -0400",
        "updated_at":"Fri, 16 Mar 2012 16:13:10 -0400",
                    "manager_role_name": null,
        "is_assignor":0,
        "is_referee":1,
        "is_observer":0,
                    "is_manager":0
    }
}

Create a Game (CREATE)

To create a user, use the POST command to /users.xml or /users.json.

The following status codes can be returned:

  • 201 Created: Successfully created a user. The response body will have an XML or JSON representation of the user you created.
  • 403 Unprocessable Entity: The user failed one or more validation checks.

Sample Request Body: POST /users.xml

<user>
  <first_name>Derick</first_name>
  <mi>A</mi>
  <last_name>Altenwerth</last_name>
  <street1>5486 Charity Via</street1>
  <street2>Langtown School</street2>
  <city>Port Tyreeland</city>
  <state>SC</state>
  <postal>46460</postal>
  <home_phone>541.885.7680</home_phone>
  <work_phone>(272)015-7299</work_phone>
  <mobile_phone>061-086-7246 x4038</mobile_phone>
  <email>lempi.renner@framiwelch.uk</email>
  <email2>leslie_fay@jerdewilkinson.name</email2>
  <grade>USSF 8</grade>
  <is_assignor>0</is_assignor>
  <is_referee>1</is_referee>
  <is_observer>0</is_observer>
        <is_manager>0</is_manager>
        <manager_role_name></manager_role_name>
</user>

Sample Request Body: POST /users.json

{
    "user":
    {
        "id":7294,
        "first_name":"Derick",
        "mi":"A",
        "last_name":"Altenwerth",
        "street1":"5486 Charity Via",
        "street2":"Langtown School",
        "city":"Port Tyreeland",
        "state":"SC",
        "postal":"46460",
        "home_phone":"541.885.7680",
        "work_phone":"(272)015-7299",
        "mobile_phone":"061-086-7246 x4038",
        "email":"lempi.renner@framiwelch.uk",
        "email2":"leslie_fay@jerdewilkinson.name",
        "grade":"USSF 8",
        "is_assignor":0,
        "is_referee":1,
        "is_observer":0,
                    "is_manager":0

    }
}

Update a Game (UPDATE)

To update a user, send a PUT command to /users/123.xml or /users/123.json. The request body should be XML, JSON, or a URL encoded string. If you are only updating a specific field, you can just include the fields you wish to change. For example, if you only want to change an email address, the request can look like this:

PUT /users/123.xml
<user><email>joseph.schmoe@example.com</email></user>

PUT /users/123.xml
user[email]=joseph.schmoe@example.com

PUT /users/123.json
{"user":{"email":"joseph.schmoe@example.com"}}

Upon successful update of the record, the response code returned will be 200 (OK).

Delete a User (DELETE)

To delete a user, issue a DELETE command to the user's URL:

DELETE /users/123.json

The server will respond with a status code 200 (OK) if the user was deleted, otherwise you will see an error response (422 Unprocessable Entity). No response body is rendered.

Validation Errors

If you try to create, update, or delete a user, and the change that you want to make validates one or more assignr.com validation rules, assignr.com will respond with a 422 Unprocessable Entity error. The response body will contain details about the error, like this:

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <messages>
    <message>Password confirmation does not match password provided.</message>
    <message>User with this name already exists.</message>
  </messages>
</error>

If JSON is requested, it will look like this:

{"error":[
    {"message": "Password confirmation does not match password provided."},
    {"message": "User with this name already exists."}
  ]
}

Related articles