REST API:record Resource

Manage Object records using the REST API.

See also:

• The REST bulk record resource to work with multiple records at one time.
• The REST composite record resource to work with a record and related records in other objects.

About the Record Resource

Available Objects

These objects are available in the record Resource

• Built-in Objects (except those deprecated, below)
• CRM Objects
• Custom Objects
• Project Tasks
• Project Phases

For each object, it is possible to access and/or manage:

• Workflow State and Owners

Predefined Custom Object Fields

Every Custom Object is created with a number of fields that are automically modified for each record.

Learn More: Custom Object#Predefined Fields

Special Considerations for Enumerated Fields

When a record contains Enumerated Fields, there are additional factors to take into account.

Learn more: Enumerated Field Behavior For REST Web Services

Deprecated Objects

These Built-in Objects can no longer be retrieved using the record Resource. (They have specific resource URLs, instead):

• USER - use the user Resource
• ROLE - use the role Resource
• TEAM - use the team Resource
• USER TEAM use the userTeam Resource

Deprecated Fields

• workflow_owner - This field has been deprecated for GETs. It is still present and can be used for updates, but it no longer contains any data when returned. Use this resource, instead: Identify_Workflow_Owners.

Requirements

• The logged-in user must have the permissions needed to access and/or modify the object in question.

Record access:

Users with View permission enabled in Role Permissions or the Access Profile can read records Users with Add permission enabled in Role Permissions or the Access Profile can add records Users with Update permission enabled in Role Permissions or the Access Profile can update records Users with Delete permission enabled in Role Permissions or the Access Profile can delete records

Access to records owned by other team members:

Read: View permission enabled in Role Permissions Update: Update permission enabled in Role Permissions Delete: Delete permission enabled in Role Permissions

Retrieve a Record

Identifies and retrieves a single record in an Object

Method

GET

URI

https://na.longjump.com/networking/rest/record/{objectName}/{recordId}

https://na.longjump.com/networking/rest/record/{objectName}/{recordId}?retrieveRecordPermissions=true

where the optional Retrieve Record Permissions Query Parameter adds extra data that tells whether the user has add or delete capabilities.

Response

<platform>
  <record>
    <field1>...value...</field1>
    <field2>...value...</field2>
    <field3 displayValue="...">...value...</field3>
        …
  </record>
</platform>

Notes:

• An enumerated field returns the field label in the displayValue attribute. The field value is returned as the data inside the tag.
• A Multi Object Lookup field has two attributes, in addition to the type attribute that is specified when you do an add or update. The syntax looks like this:

<field_name type="{objectName}" 
    uri="{REST_resource_record_id}" 
    display_value="{textual_record_identifier}">{record_id}</field>

where the Record Locator is the information that is displayed for the selected record.

• For example, in the Sample Order Processing System, if priority tags were in a separate table, then the contents of the tag field might look like this:

<tag type="Priority_Tag" 
    uri="https://{domain}/networking/rest/record/Priority_Tag/9467890" 
    displayValue="Rush, Overnight">9467890</tag>

Dynamic Search

Method

GET

URI

https://na.longjump.com/networking/rest/record/{objectName}?{query_params}

https://na.longjump.com/networking/rest/record/{objectName}?{query_params}&retrieveRecordPermissions=true

where:

• {objectName} is an Object Type Identifier or Database View ID
• The optional Retrieve Record Permissions Query Parameter adds extra data that tells whether the user has add or delete capabilities.

Sample Search

?fieldList=name,id & filter=name contains 'smith' & sortby='id'

(See the object or view being searched for a list of field names.)

Query Parameters

• fieldList - A comma-separated list of field names to retrieve

• The asterisk (*) wildcard specifies all fields
• Use the REST API:field Resource to get a complete list of fields
• Field lists for database views need to specify the object's alias, as well as the field name.

• filter - Filtering criteria to filter the records

• For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

• pageSize - Number of records to retrieve from the result set in order to make a "page".
• page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

• getTotalRecordCount returns the number of total records.
  Causes the following structure to be returned, where N is the total number of records:

<platform> 
   ...
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

• sortBy - Field name for primary sort
  Ex: &sortBy=name
• sortOrder - Sort order of the primary field, either "asc" or "desc" (ascending or descending)
  Ex: &sortOrder="desc"
• sortBy2 - Field name for secondary sort
• sortOrder2 - Sort order of the second field, either "asc" or "desc" (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Note: When searching a multi-object lookup field, the object ID (not name) must be specified.
Syntax: {object_id}:{record_id}

Important: When searching the CRM Objects using the REST API, you need to use the (mostly uppercase) REST versions of the field names when specifying Field Lists and Filter Expressions in the Dynamic Search Parameters. Those field names are returned, as well. For example: OWNERID. When you do an HTTP GET, on the other hand, tags are returned in lowercase, with underscores. For example: owner_id. Those tag names must be specified when doing an HTTP PUT. Those are also the field names you use in the GUI and in the Java APIs. CRM Objects ACCOUNT LEAD CONTACT CONTRACT CASE OPPORTUNITY PRODUCT PRICE BOOK

Response

Here is the response for a search on a custom object where ObjectName is the name of the custom object:

<platform>
    <record>
        <field1>...value...</field1>
        <field2>...value...</field2>
        <field3 displayValue="...">...value...</field3>
    </record>
    ...
    <message>
        <code>0</code>
        <description>Success</description>
        </message>
    <recordCount>30</recordCount>
</platform>

Notes:

• An enumerated field returns the field label in the displayValue attribute. The field value is returned as the data inside the tag.

Response

Here is the response for a search on a database view where ObjectName is the DatabaseViewId:

<platform>
    <record>
        <alias1.fileName1>value1</alias1.fileName1>
        <alias1.fileName2>value1</alias1.fileName2>
        <alias2.fileName1>value1</alias2.fileName1>
        <alias2.fileName2>value1</alias2.fileName2>
        ...
    </record>
    <record>
    ...
    </record>
        <message>
            <code>0</code>
            <description>Success</description>
        </message>
    <recordCount>30</recordCount>
</platform>

Add a Record

Adds a record to an Object

Method

POST

URI

https://na.longjump.com/networking/rest/record/{objectName}?{query_parameters}

Query Parameters

• retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

<platform>
    <record>
        <field1>...</field1>
        <field2>...</field2>
        ...
        ...
    </record>
</platform>

Notes:

• Each <fieldN> element has the name of a field in the object. For example:

<company_name>ABC Co.</company_name>
<street_address>21 Jump Street</street_address>

• When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:

<field_name type="{objectName}">{record_id}</field>

For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:

<tag type="Priority_Tag">9467890</tag>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <id>...</id>     <!-- record ID -->  
</platform>

Update a Record

Updates a record in an Object.

Method

PUT

URI

https://na.longjump.com/networking/rest/record/{objectName}/{recordId}?{query_parameters}

Query Parameters

• retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

<platform>
    <record>
        <field1>...</field1>
        <field2>...</field2>
        ...
        ...
    </record>
</platform>

Notes:

• Each <fieldN> element has the name of a field in the object. For example:

<company_name>ABC Co.</company_name>
<street_address>21 Jump Street</street_address>

• When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:

<field_name type="{objectName}">{record_id}</field>

For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:

<tag type="Priority_Tag">9467890</tag>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

If the ?retrieveRecord=true query is included:

• If ?retrieveRecord=true, the record is also returned
• If ?retrieveRecord=false or is not present, the record is not returned

Delete a Record

Deletes a record in an Object

Method

DELETE

URI

https://na.longjump.com/networking/rest/record/{objectName}/{recordId}

Request

No request body accompanies the resource.

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

Multipart Operations for Raw Data

To include binary data in an XML stream, it is encoded and included in a multipart REST request (a request that contains a normal XML segment and an additional segment for each request field that holds raw data).

Add a Multipart Record

Adds a record to an Object when one or more fields contain raw data.

Method

POST

URI

https://na.longjump.com/networking/rest/record/{objectName}?{query_parameters}

Query Parameters

• isBase64Encoded (optional)

• true: File content is encoded binary data For example, an image.
• false: File content is not encoded. For example, a text file. (default)

• retrieveRecord (optional)

• true: the record is also returned
• false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

Content-Type: multipart/form-data; boundary=.............................103832778631715

--.............................103832778631715
Content-Disposition: form-data; name="__xml_data__"
content-type: application/xml

    <platform>
        <record>
            <field1>...</field1>
            <field2>...</field2>
            <image_field>image1.jpg</image_field>
             ...
        </record>
    </platform>
.............................103832778631715
Content-Disposition: form-data; name="image_field"; filename="image1.jpg"
content-type: application/octet-stream

{encoded contents of file}
.............................103832778631715--

The Content-type of the request is set to multipart/form-data with an appropriate boundary.

The first part contains the xml record post request and has a Content-type application/xml or application/json. The name of the part is either __xml_data__ or __json_data__.

The <image_field> field contains the file name: image1.jpg.

The next part of the request is the actual file. The Content-type is application/octet-stream. Note that the 'name' attribute in the content disposition points to the image field tag in the xml of the first part (ie. 'image_field'). This links the file part to the respective field in the xml. The 'filename' attribute of the content disposition is the file name of the file being uploaded to that field (i.e. image1.jpg).

Multiple files can be attached to their respective fields in that manner.

Response

 <platform>
     <message>
         <code>0</code>
         <description>Success</description>
     </message>
 </platform>

See also: REST API:Error Codes

Sample Client

Here is a sample client that uploads an image to an image field.

import java.io.File;

import javax.ws.rs.core.MediaType;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.URI;
import org.apache.commons.httpclient.methods.PutMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class MultipartRecord
{
    public static void main(String[] args)
    {
        try
        {
            File f = new File("c:\\csvs\\image1.jpg");
            
            HttpClient client = new HttpClient();

            //Add a record to a custom object called "HOMEPAGE"
            PostMethod postMethod = new 
                PostMethod("https://{domain}/networking/rest/record/HOMEPAGE/");
            
            //Set the session for this request.
            postMethod.setRequestHeader("Cookie", "JSESSIONID=A741270662A86F796DA16646F0708C43");

            //The first attribute of the FilePart constructor refers to the image field name 
            //ie.image_field
            FilePart filePart = new FilePart("image_field", f);
            
            //Set the content type of the filePart
            filePart.setContentType(MediaType.APPLICATION_OCTET_STREAM);

            //Create the xml part of the request
            // __xml_data__ is required for the name attribute 
            // If the content type is json, use __json_data__
            StringPart sp = new StringPart("__xml_data__",
              "<platform><record><field1>Some text field</field1>"
            + "<image_field>image1.jpg</image_field></record></platform>");
            
            //Set the Content-type of the xml part
            sp.setContentType(MediaType.APPLICATION_XML);
            
            final Part[] parts = { sp, filePart };

            postMethod.setRequestEntity(new MultipartRequestEntity(parts, postMethod.getParams()));

            int executeMethod = client.executeMethod(postMethod);
        }
        catch(Exception e)
        {
            System.out.println("Exception");
        }
    }
}

Update a Multipart Record

Updates a record in an Object when one or more fields contain raw data.

Note: Normal update rules are observed. For example, if an image field is specified, and the existing record field already contains an image, then the old image is deleted and the new one is uploaded in it's place.

Method

PUT

URI

https://na.longjump.com/networking/rest/record/{objectName}/{recordId}?{query_parameters}

Query Parameters

• isBase64Encoded (optional)

• true: File content is encoded binary data For example, an image.
• false: File content is not encoded. For example, a text file. (default)

• retrieveRecord (optional)

• true: the record is also returned
• false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

The format of the request is identical to that shown in Add a Multipart Record.

Response

      <platform>
          <message>
              <code>0</code>
              <description>Success</description>
          </message>
      </platform>

See also: REST API:Error Codes

Sample Client

Here is a sample client that updates an image in an image field.

import java.io.File;

import javax.ws.rs.core.MediaType;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.URI;
import org.apache.commons.httpclient.methods.PutMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;


public class MultipartRecord
{
    public static void main(String[] args)
    {
        try
        {
            File f = new File("c:\\csvs\\image1.jpg");
            
            HttpClient client = new HttpClient();

            //Update a record in a custom object called "HOMEPAGE"
            PutMethod PutMethod = 
               new PutMethod("https://{domain}/networking/rest/record/HOMEPAGE/{recordId}");
            
            //Set the session for this request.
            PutMethod.setRequestHeader("Cookie", "JSESSIONID=A741270662A86F796DA16646F0708C43");

            //The first attribute of the FilePart constructor refers to 
            //the image field name ie.image_field
            FilePart filePart = new FilePart("image_field", f);
            
            //Set the content type of the filePart
            filePart.setContentType(MediaType.APPLICATION_OCTET_STREAM);

            //Create the xml part of the request
            // __xml_data__ is required for the name attribute 
            // If the content type is json, use __json_data__
            StringPart sp = new StringPart("__xml_data__",
                "<platform><record><field1>Some text field</field1>"
              + "<image_field>image1.jpg</image_field></record></platform>");
            
            //Set the Content-type of the xml part
            sp.setContentType(MediaType.APPLICATION_XML);
            
            final Part[] parts = { sp, filePart };

            PutMethod.setRequestEntity(new MultipartRequestEntity(parts, PutMethod.getParams()));

            int executeMethod = client.executeMethod(PutMethod);
        }
        catch(Exception e)
        {
            System.out.println("Exception");
        }
    }
}