Example

Before getting started you will need 3 pieces of information.

• API Key
• Customer API Address (supplied by RollMaster staff)
• Username/Password (for user authentication)

For the purpose of this example we will use the Demo API (https://api.rmaster.com/api/demo/). The RollMaster API uses RESTful based practices. All data is returned in JSON format.

We will walk through authenticating, calling for a customer list, creating a new customer record, updating the customer record, and finally closing the session.

Step 1 - Authentication

Almost all calls in the RollMaster API require user credentials. API calls follow RollMaster permissions, and thus require a user identification to be attached to every transaction. Authentication is performed only a single time with the API. Once the user and password are used with the POST token endpoint you will get a token to use for authentication from then on. There are two kinds of tokens, the first being a temporary type that has a minutes timeout. The second is designed for API to API interaction and will expire after a year of non-use. Both are auto-renewing when any calls is made to the API. If a token has a 5 minute timeout and any API call is made within that time frame then the timeout resets for that token. The token expires when no calls have been made within the timeout period and will no longer be usable for API calls. If you want to 'keep alive' the token, then you can pass a call to the GET token endpoint to reset the timer.

{
            "COMPANIES": [
                {
                    "COMPANY": "99",
                    "REGION": "1 ",
                    "BRANCH": "1 ",
                    "SELECTED": "Y"
                },
                {
                    "COMPANY": "99",
                    "REGION": "1 ",
                    "BRANCH": "2 ",
                    "SELECTED": "Y"
                },
                {
                    "COMPANY": "99",
                    "REGION": "B ",
                    "BRANCH": "A ",
                    "SELECTED": "Y"
                }
            ],
            "ALIAS": "example_alias",
            "TOKEN": "7645a68bf77e32ab39152438be4bfbed",
            "TIMEOUT": "010",
            "IDLETIMEOUT": "005"
        }

From this point on we will use the TOKEN object as our authentication token.

Step 2 - Get Customer List

We will return a list of customers that are currently in the system. We will be passing the token object from step 1 as part of the header information. The token can be passed in the header or in the querystring/formData depending on the call type.

[
    {
        "C_CO": "99",
        "C_CID": "",
        "C_NAME": "John Doe",
        "C_PHONE": "   -   -",
        "C_PHONE2": "",
        "C_FAX": "",
        "C_EMAIL": "F",
        "C_DTLSTINV": "00000000",
        "C_DTLSTPAY": "00000000",
        "C_DTOPENED": "00000000"
    },
    {
        "C_CO": "99",
        "C_CID": "  BADJOB",
        "C_NAME": "JOB OPENED IN ERROR..CLOSE",
        "C_PHONE": "111-111-1111",
        "C_PHONE2": "",
        "C_FAX": "",
        "C_EMAIL": "n/a",
        "C_DTLSTINV": "02282018",
        "C_DTLSTPAY": "03202018",
        "C_DTOPENED": "12012005"
    },
    ...
]
                 

This will return a list of all qualifying customer records. Be aware that it might be a very large return that should be taken in chunks based on parameters that can limit the amount of return (see endpoint for more info).

Step 3 - Create a Customer

Now that we have checked for a particular customer record, we will create one that matches the information we have. Be aware that no all the POST calls to create records are idempotent. If a POST is called to create a new customer record then multiple times with the same information, it will fail as the record will already exist on the second call. Not all calls will have the same capability depending on the data being created.

{
    "COMPANY": "99",
    "C_CID": "COMPANY1",
    "C_NAME": "COMPANY TESTING",
    "C_ADDR1": "ADDRESS 1 TESTING",
    "C_ADDR2": "ADDRESS 2 TESTING",
    "C_ZIPCD": "12345",
    "C_PHONE": "123-456-7890",
    "C_EMAIL": "EMAIL@SERVER.COM",
    "C_CITY": "CITY",
    "C_STATE": "STATE",
    "C_COUNTRY": "US"
}

{
    "RETURN": "CUSTOMER RECORD COMPANY1 CREATED"
}

Step 4 - Update Customer Record

PATCH calls are idempotent. Only data passed in as part of the payload will be changed. All other information will remain the same on the record.

{
    "COMPANY": "99",
    "C_CID": "COMPANY1",
    "C_NAME": "COMPANY TESTING CHANGED"
}

{
    "RETURN": "CUSTOMER RECORD COMPANY1 CHANGED"
}

Step 5 - Delete Token

Once the transactions are complete you will want to delete the session token to free up the user license.

{
    "RETURN":"SESSION ENDED"
}