REST POST and PUT Tutorial

Creating and Updating Objects

The important aspect of creating and updating objects in the Gotransverse API is understanding the correct parameters to pass, and the format of the request. Basically, it's not about how to make the request, it's about what to put in the request.

Simple Example

Let's look at a simple example: posting an adjustment. The body for this command contains only one parameter: adjustment.

POST https://my.tractbilling.com/t/s/r/1.28/adjustments/<eid>/post

<postAdjustment xmlns="http://www.tractbilling.com/billing/1_28/domain">
<adjustment eid="13660"></postAdjustment>

Note two things:

  • The namespace: xmlns="http://www.tractbilling.com/billing/1_28/domain". The namespace must be provided as an attribute in the top-level element in the body of your request.
  • the eid of the adjustment was used in this command. EIDs are important for queries, and they're especially important for creating objects.

Finding Necessary EIDs

To update objects, you will always need the EID of the object you're updating and the EID of the object that you're adding/removing/changing. To create objects, you need the EIDs of any existing elements used to construct the object.

In the example above, the only required element was the adjustment to be updated. Use the query keys for adjustment to find the adjustment's EID. The keys indicate that you can search for an adjustment by the EID or account number of the billing account it's associated with, or the EID or number of the invoice it is to be applied to. If needed, you can use status in conjunction to narrow your results.

Below is an example query and result used to get the adjustment EID. Note the eid attribute for adjustment - 13660.

GET https://my.tractbilling.com/t/s/r/1.28/adjustments?accountNum=1089

        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:adjustments xmlns="http://www.tractbilling.com/billing/1_28/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_28/domain/rest" pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
    <adjustment occurredOn="2015-10-01T14:57:24.000-05:00" amount="5.00" description="Loyalty credit" invoiced="false" credit="true" status="PENDING" type="MANUAL" manualInvoiceApplication="false" unappliedAmount="0.00" creditNumber="277" eid="13660" queryScope="SHALLOW">
        <billingAccount eid="51800" queryScope="EID"/>
        <reason name="Default Credit Adjustment Reason" description="Default Credit Adjustment Reason" status="ACTIVE" creditOnly="true" level="PRIMARY" eid="136"/>
    </adjustment>
</ns2:adjustments> 

Now a more complicated example: creating a billing account.

Creating a Billing Account

To create a billing account, you must include the following in your request: 

  • a selected bill type attribute (email, paper, or none)
  • a billing cycle EID
  • a billing account category EID
  • a person or organization OR the EID of an existing person/organization.

You'll need to query for the bill cycle eid and billing account category IDs. Quick refresher:

https://my.tractbilling.com/t/s/r/1.28/billCycles?type=_______

https://my.tractbilling.com/t/s/r/1.28/billingAccountCategories

When creating a person or organization, you must include the required parameters for the type. The example below uses the minimum for person: a first name, last name, and billing address.

Example Payload

POST https://my.tractbilling.com/t/s/r/1.28/billingAccounts

<billingAccount billType="NONE" xmlns="http://www.tractbilling.com/billing/1_28/domain">
        <dailyBillCycle eid="1688"/>
        <organization eid="55572"/>
        <billingAccountCategory eid="80"/>
        <person firstName="Tim" lastName="Curri">
          <addresses>
           <postalAddress purpose="BILLING" country="USA" city="Austin" regionOrState="TX" 
 postalCode="78701" line1="123 Interesting Street"/>
          </addresses>
        </person>
</billingAccount>  

Example Response

201 Created

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<createResponse xmlns="http://www.tractbilling.com/billing/1_28/domain/rest" type="BillingAccount" eid="52926"/>

Errors

With complex POST commands that require many EIDs, elements, and attributes, mistakes are bound to happen. Here are some examples to illustrate common errors.

415 Unsupported media type Ensure that application/xml is specified in your header as the content type
400 Bad request Enter a valid entity in <type></type>.
422 Unprocessable entity Various validation errors. Generally the responses are robust. Example: 
<errorDescription>Validation error: addresses list is required</errorDescription> <failureReason>VALIDATION_FAILURE</failureReason>
500 Unmarshalling Error: Unexpected 'character' in attribute value at [row,col {unknown-source}]: [row ,column] Correct the character at the specified location.
500 Mismatched input input characters expecting expected datatype Check the datatype you're trying to enter; strings are double quoted, unless in a clause, where they are single quoted.