2Overview of Using the Oracle CRM On Demand REST API

About Oracle CRM On Demand REST API

REST stands for Representational State Transfer and is an architectural style that makes use of existing technology and protocols of the Web, such as HTTP and JSON. A REST API allows you to send data requests and receive responses over an HTTP interface. REST requests and responses include a header and a body. The header defines the operating parameters of the interaction and contains metadata, such as HTTP methods or encoding information. The body contains data that you want to transmit over the network. The body header contains instructions on how to use the transmitted data. The body can also remain empty.

An important concept of REST is the existence of resources, which are sources of specific information. Each resource is referenced with a global identifier, a URL in HTTP. To manipulate these resources, clients and servers communicate through an HTTP interface and exchange abstractions of these resources, such as a record or a list of records.

The Oracle CRM On Demand REST API exposes Oracle CRM On Demand records (resources), allowing you to integrate with Oracle CRM On Demand by using the GET, POST, PATCH, and DELETE HTTP methods to take actions on the Oracle CRM On Demand Server.

For example, you can do the following:

  • Use the POST HTTP method to create a new Oracle CRM On Demand resource.

  • Use the GET HTTP method to retrieve information about an Oracle CRM On Demand resource.

  • Use the PATCH HTTP method to update an Oracle CRM On Demand resource.

  • Use the DELETE HTTP method to delete an Oracle CRM On Demand resource.

  • Perform a query or search on Oracle CRM On Demand collection resources.

Use the Oracle CRM On Demand REST API for interactive operations with Oracle CRM On Demand. For Oracle CRM On Demand bulk operations, use Web services. For more information about Oracle CRM On Demand Web services, see Oracle Web Services On Demand Guide.

About Oracle CRM On Demand REST API Requests and Responses

To use the Oracle CRM On Demand REST API to interact with Oracle CRM On Demand, you must send a request to the Oracle CRM On Demand Server.

A request can include the following information:

  • A request URL. For more information about the Oracle CRM On Demand REST API URL, see Oracle CRM On Demand REST API URL Format.

  • The object type of the Oracle CRM On Demand resource that you want to take action on. For more information about the supported Oracle CRM On Demand resources, see Oracle CRM On Demand REST API Supported Resources.

  • The HTTP method that you use to perform a REST API operation (create, retrieve, update, or delete) on the Oracle CRM On Demand Server. For more information about supported HTTP methods, see Supported HTTP Methods.

  • Header information to define the parameters of the interaction with the Oracle CRM On Demand Server and the information and format you want in the response. For more information about supported HTTP headers, see Supported HTTP and Oracle CRM On Demand Header Fields.

  • Optional query parameters to search for specific resources in a collection. For more information about querying a collection, see Querying a Collection Resource.

  • Optional sorting parameters to sort collection lists. For additional information about sorting, see Sorting Collection Resources.

  • Optional paging parameters to limit large collection resource lists. For additional information about paging, see Paging Collection Resources.

After the Oracle CRM On Demand Server processes the request, the server sends back a response. The response body contains the results of the REST API call and also additional metadata and information based on what was specified in the request.

The response can include the following information:

Oracle CRM On Demand REST API URL Format

The supported Oracle CRM On Demand resources are accessed by using a URL. The Oracle CRM On Demand REST API uses the following URL formats for top-level and child resources:

The top-level format is as follows:

OnDemand/user/Rest/latest/<objects>

The child format is as follows:

OnDemand/user/Rest/latest/<ParentObject>/<ParentRowId>/child/<childobjects>

An example top-level resource structure is as follows:

OnDemand/user/Rest/latest/Accounts

An example child resource structure is as follows:

OnDemand/user/Rest/latest/Accounts/1QA2-21SEF/child/AccountAddresses

where:

  • OnDemand indicates the name of the integration product, Oracle CRM On Demand.

  • user is always user and cannot be modified.

  • Rest is the endpoint for the REST API URL.

  • latest indicates the version number for Oracle CRM On Demand.

  • <objects> indicates the name of the Oracle CRM On Demand REST API resource. For more information about supported Oracle CRM On Demand resources, see Oracle CRM On Demand REST API Supported Resources.

  • <ParentObject> indicates the name of the Oracle CRM On Demand REST API parent resource.

  • <ParentRowID> indicates the row ID for the parent resource.

  • child indicates that a child resource is referenced.

  • <childobjects> indicates the name of the Oracle CRM On Demand REST API child resource. For more information about the supported Oracle CRM On Demand child resources, see Oracle CRM On Demand REST API Supported Resources.

Oracle CRM On Demand REST API Supported Resources

A REST API resource is a piece of information, such as a data record or a list of records. Each Oracle CRM On Demand REST API resource is identified by a named URL, and it is accessed using standard HTTP methods. For more information about URL format, see Oracle CRM On Demand REST API URL Format.

Note: When you use the Oracle CRM On Demand REST API to call Oracle CRM On Demand resources, you must use the plural form. For example, use Accounts and not Account. If you customized the resource name, then use the custom resource name. For more information about customizing resource names, see Customizing REST API Integration Tags.

The REST API supports top-level and child resources. A supported top-level resource will also appear as a child of another supported object provided it is a one-to-many relationship. You can see which parent and child resources are supported by running describe requests. For more information about describe requests, see Retrieving Metadata about Oracle CRM On Demand Resources. In addition, see the describe request examples provided in Retrieving Metadata for All Oracle CRM On Demand Resources and Retrieving Metadata for All Oracle CRM On Demand Resources.

The REST API supports the relationship between accounts, contacts, and their opportunities as a many-to-many parent-child relationship. For more information about associating accounts to contact resources, see Associating Accounts to Contacts Resources. For more information about associating contacts to accounts and opportunities, see Associating Contacts to Accounts and Opportunities Resources.

The REST API supports create, retrieve, update and delete actions on book and team child resources. Existing book and team resources can also be associated with other resources for which book relationships are supported. For information about associating books to REST API resources, see Associating Books to REST API Resources. For information about associating teams to REST API resources, see Associating Teams to REST API Resources.

The REST API supports not only core Oracle CRM On Demand top-level and child resources, but also industry-specific resources. Top-level and child resources and resources available with industry-specific editions of the application are covered in the following topics:

    About Working with Oracle CRM On Demand Resources

    You can use Oracle CRM On Demand REST API resources to interact with Oracle CRM On Demand. For example, you can:

      Supported Core Oracle CRM On Demand Resources

      The following table contains the supported top-level core Oracle CRM On Demand resources for the Oracle CRM On Demand REST API, the supported operations, and whether the resource supports using enclosure to perform actions on attachments. For information about using the REST API to interact with Oracle CRM On Demand supported top-level and child core resources, see About Using the Oracle CRM On Demand REST API with Oracle CRM On Demand.

      Table Supported Oracle CRM On Demand Core Top-Level Resources, Operations, and Enclosure Actions

      Top-Level Resources Create Retrieve Update Delete Enclosure

      Accounts

      Yes

      Yes

      Yes

      Yes

      No

      Activities

      Yes

      Yes

      Yes

      Yes

      No

      Allotment Usages

      No

      Yes

      No

      No

      No

      Assets

      Yes

      Yes

      Yes

      Yes

      No

      Books

      Yes

      Yes

      Yes

      Yes

      No

      Campaigns

      Yes

      Yes

      Yes

      Yes

      No

      Categories

      Yes

      Yes

      Yes

      Yes

      No

      Contacts

      Yes

      Yes

      Yes

      Yes

      No

      Custom Objects 1

      Yes

      Yes

      Yes

      Yes

      Yes

      Custom Objects 2

      Yes

      Yes

      Yes

      Yes

      Yes

      Custom Objects 3

      Yes

      Yes

      Yes

      Yes

      Yes

      Custom Objects 4-40

      Yes

      Yes

      Yes

      Yes

      Yes

      Groups

      Yes

      Yes

      Yes

      Yes

      No

      Leads

      Yes

      Yes

      Yes

      Yes

      No

      Modification Trackings

      Yes

      Yes

      Yes

      Yes

      No

      Notes

      Yes

      Yes

      Yes

      Yes

      No

      Opportunities

      Yes

      Yes

      Yes

      Yes

      No

      Products

      Yes

      Yes

      Yes

      Yes

      No

      Service Allotments

      No

      Yes

      No

      No

      No

      Service Requests

      Yes

      Yes

      Yes

      Yes

      No

      Solutions

      Yes

      Yes

      Yes

      Yes

      No

      Users

      Yes

      Yes

      Yes

      No

      No

        Supported Partner Relation Management Edition Resources

        The following table contains the supported Oracle CRM On Demand resources available with Oracle CRM On Demand Partner Relationship Management Edition, the supported operations, and whether the resource supports using enclosure to perform actions on attachments.

        Table Supported Partner Relation Management Edition Resources, Operations, and Enclosure Actions

        Partner Relation Management Resources Create Retrieve Update Delete Enclosure

        Accreditations

        Yes

        Yes

        Yes

        Yes

        No

        Accreditation Requests

        Yes

        Yes

        Yes

        Yes

        No

        Applications

        Yes

        Yes

        Yes

        Yes

        No

        Certification Requests

        Yes

        Yes

        Yes

        Yes

        No

        Courses

        Yes

        Yes

        Yes

        Yes

        No

        Course Enrollments

        Yes

        Yes

        Yes

        Yes

        No

        Deal Registrations

        Yes

        Yes

        Yes

        Yes

        No

        Exams

        Yes

        Yes

        Yes

        Yes

        No

        Exam Registrations

        Yes

        Yes

        Yes

        Yes

        No

        Funds

        Yes

        Yes

        Yes

        Yes

        No

        MDF Requests

        Yes

        Yes

        Yes

        Yes

        No

        Partners

        Yes

        Yes

        Yes

        Yes

        No

        Price Lists

        Yes

        Yes

        Yes

        Yes

        No

        Price List Line Items

        Yes

        Yes

        Yes

        Yes

        No

        Special Pricing Products

        Yes

        Yes

        Yes

        Yes

        No

        Special Pricing Requests

        Yes

        Yes

        Yes

        Yes

        No

          Supported Life Sciences Edition Resources

          The following table contains the supported top-level Oracle CRM On Demand resources available with Oracle CRM On Demand Life Sciences Edition, the supported operations, and whether the resource supports using enclosure to perform actions on attachments.

          Table Supported Life Sciences Edition Resources, Operations, and Enclosure Actions

          Top-Level Resources Create Retrieve Update Delete Enclosure

          Allocations

          Yes

          Yes

          Yes

          Yes

          No

          Blocked Products

          Yes

          Yes

          Yes

          Yes

          No

          Business Plans

          Yes

          Yes

          Yes

          Yes

          No

          Call Activity Histories

          No

          Yes

          No

          No

          No

          Contact State Licenses

          Yes

          Yes

          Yes

          Yes

          No

          Events

          Yes

          Yes

          Yes

          Yes

          No

          HCP Contact Allocations

          Yes

          Yes

          Yes

          Yes

          No

          Inventory Audit Reports

          Yes

          Yes

          Yes

          Yes

          No

          Inventory Periods

          Yes

          Yes

          Yes

          Yes

          No

          Message Responses

          Yes

          Yes

          Yes

          Yes

          No

          Messaging Plans

          Yes

          Yes

          Yes

          Yes

          No

          Messaging Plan Items

          Yes

          Yes

          Yes

          Yes

          No

          Messaging Plan Item Relations

          Yes

          Yes

          Yes

          Yes

          No

          Objectives

          Yes

          Yes

          Yes

          Yes

          No

          Orders

          Yes

          Yes

          Yes

          Yes

          No

          Order Items

          Yes

          Yes

          Yes

          Yes

          No

          Plan Accounts

          Yes

          Yes

          Yes

          Yes

          No

          Plan Contacts

          Yes

          Yes

          Yes

          Yes

          No

          Plan Opportunities

          Yes

          Yes

          Yes

          Yes

          No

          Related Disclaimers

          Yes

          Yes

          Yes

          Yes

          No

          Sample Disclaimers

          Yes

          Yes

          Yes

          Yes

          No

          Sample Inventories

          Yes

          Yes

          Yes

          Yes

          No

          Sample Lots

          Yes

          Yes

          Yes

          Yes

          No

          Sample Requests

          Yes

          Yes

          Yes

          Yes

          No

          Sample Request Items

          Yes

          Yes

          Yes

          Yes

          No

          Sample Transactions

          Yes

          Yes

          Yes

          Yes

          No

          Signatures

          Yes

          Yes

          Yes

          Yes

          No

          Transaction Items

          Yes

          Yes

          Yes

          Yes

          No

            Supported Financial Services Edition Resources

            The following table contains the supported Oracle CRM On Demand resources available with Oracle CRM On Demand Financial Services Edition, the supported operations, and whether the resource supports using enclosure to perform actions on attachments.

            Table Supported Financial Services Edition Resources, Operations, and Enclosure Actions

            Top-Level Resources Create Retrieve Update Delete Enclosure

            Claims

            Yes

            Yes

            Yes

            Yes

            No

            Coverages

            Yes

            Yes

            Yes

            Yes

            No

            Damages

            Yes

            Yes

            Yes

            Yes

            No

            Financial Accounts

            Yes

            Yes

            Yes

            Yes

            No

            Financial Account Holders

            Yes

            Yes

            Yes

            Yes

            No

            Financial Account Holdings

            Yes

            Yes

            Yes

            Yes

            No

            Financial Plans

            Yes

            Yes

            Yes

            Yes

            No

            Financial Products

            Yes

            Yes

            Yes

            Yes

            No

            Financial Transactions

            Yes

            Yes

            Yes

            Yes

            No

            Households

            Yes

            Yes

            Yes

            Yes

            No

            Insurance Properties

            Yes

            Yes

            Yes

            Yes

            No

            Involved Parties

            Yes

            Yes

            Yes

            Yes

            No

            Policies

            Yes

            Yes

            Yes

            Yes

            No

            Policy Holders

            Yes

            Yes

            Yes

            Yes

            No

            Portfolios

            Yes

            Yes

            Yes

            Yes

            No

              Supported Automotive Edition Resources

              The following table contains the supported Oracle CRM On Demand resources available with Oracle CRM On Demand Automotive Edition, the supported operations, and whether the resource supports using enclosure to perform actions on attachments.

              Table Supported Automotive Edition Resources, Operations, and Enclosure Actions

              Top-Level Resources Create Retrieve Update Delete Enclosure

              Dealers

              Yes

              Yes

              Yes

              Yes

              No

              Vehicles

              Yes

              Yes

              Yes

              Yes

              No

                Supported HTTP Methods

                The following table contains the HTTP methods supported by Oracle CRM On Demand and the corresponding REST API operation.

                Table Supported HTTP Methods

                HTTP Method REST API Operation Description

                GET

                Retrieve

                The GET method retrieves an Oracle CRM On Demand resource.

                POST

                Create

                The POST method creates a new Oracle CRM On Demand resource.

                PATCH

                Update

                The PATCH method updates an Oracle CRM On Demand resource.

                DELETE

                Delete

                The DELETE method deletes an Oracle CRM On Demand resource.

                Note: The HTTP PUT method is only supported for Add and Update REST API operations for enclosure attachments. For more information about working with attachments, see Working with Resource Attachments.

                Supported HTTP and Oracle CRM On Demand Header Fields

                HTTP header fields are components of the REST API message header for requests and responses that define the operating parameters of the REST API transaction with Oracle CRM On Demand.

                The following table contains the HTTP and Oracle CRM On Demand header fields supported by the Oracle CRM On Demand REST API.

                Table Supported HTTP Header Fields

                HTTP Header Field Name Description Example

                Content-Type

                The HTTP request and response header field that indicates the content type of the message body. The Oracle CRM On Demand REST API supports only JSON encoding for the request body.

                The Content-Type field is used with POST and PATCH requests. When submitting a POST or PATCH request, you typically supply a body with the request. You can indicate the format of the response by setting the HTTP Content-Type header on the request.

                Content-Type: application/vnd.oracle.adf.resource+json

                Content-Encoding

                The HTTP request header field that indicates the encoding for the response message.

                Accept-Encoding: gzip, deflate

                Content-Language

                The HTTP response header that indicates the language the content is in.

                Content-Language: da

                Accept

                The HTTP request header field that indicates the content types that are valid in the response message.

                Accept: text/plain

                Accept-Language

                The HTTP request header that indicates the languages that are valid for the response message. For more information about language formats, see Language Format. For information about supported language codes, see Supported Languages.

                Accept-Language: en-US

                Location

                The HTTP response header that indicates the location of a new resource that has been created.

                Location: https://<host>/OnDemand/user/Rest/latest/Accounts/1QA2-21SEFX

                LOVLanguageMode

                The Oracle CRM On Demand request header field that indicates whether language independent codes (LIC) or language dependent codes (LDC) are returned in the message response. For more information about the LOVLanguageMode input argument, see Special Search Fields.

                LOVLanguageMode: LIC

                JSESSIONID

                The Oracle CRM On Demand response header field that indicates the session ID for login authentication and session management. For more information about login authentication, see Login with Oracle CRM On Demand REST API.

                JSESSIONID=sessionidvalue

                Oracle CRM On Demand REST API Formats

                The Oracle CRM On Demand REST API uses the language, date, time, currency, and number formats described in this topic.

                  Language Format

                  For requests, you can use the standard HTTP Header Accept-Language to specify what language to return. You can list the preferred language codes in the Accept-Language header, and Oracle CRM On Demand parses the header and selects the first language code listed in the header. For more information about the languages supported by Oracle CRM On Demand and the corresponding language codes, see Supported Languages.

                  For example:

                  Accept-Language : en-us, fr-f, es
                  

                  In the previous example, the user prefers US-English. If US-English is not supported, then the user will accept French in France. If French is not supported, then the user will accept any type of Spanish.

                  If either the header is not present or if the language could not be determined from the header, then the response will have the user set the language. A response uses standard HTTP Header Content-Language to specify the language returned. For additional information about HTTP headers, see Supported HTTP and Oracle CRM On Demand Header Fields.

                    Supported Languages

                    The following table lists the supported languages for the Oracle CRM On Demand REST API with the corresponding language code.

                    Table Supported Languages

                    Supported Language REST API Language Code

                    Danish

                    da_DK

                    German

                    de_DE

                    English (UK)

                    en_GB

                    English (USA)

                    en_US

                    Spanish

                    es_ES

                    Finnish

                    fi_FI

                    French

                    fr_FR

                    Italian

                    it_IT

                    Japanese

                    ja_JP

                    Korean

                    ko_KR

                    Dutch

                    nl_NL

                    Norwegian

                    no_NO

                    Polish

                    pl_PL

                    Portuguese (Brazil)

                    pt_BR

                    Portuguese (Portugal)

                    pt_PT

                    Russian

                    ru_RU

                    Swedish

                    sv_SE

                    Thai

                    th_TH

                    Turkish

                    tr_TR

                    Chinese (Simplified)

                    zh_CN

                    Chinese (Traditional)

                    zh_TW

                      Date and Time Formats

                      For all dates and times displayed, the time zone is the logged in user’s time zone, which is determined from the user’s locale.

                      All date fields are displayed in the format YYYY-MM-DD format, for example:

                      2014-11-03
                      

                      Datetime fields for the Oracle CRM On Demand REST API are displayed in the following format:

                      YYYY-MM-DDTHH:mm:ssZ
                      

                      An example of a date and time in this format is:

                      2014-11-03T18:00:12Z
                      

                      This example represents 6:00 PM on the third of November 2014, in the user’s time zone.

                        Currency Formats

                        Currency fields for the Oracle CRM On Demand REST API requests use the following format:

                        currencyfieldname: currencyfieldvalue 
                        

                        Currency fields for the Oracle CRM On Demand REST API responses are displayed in the following format:

                        currencyfieldname:
                        {
                        type: "currency",
                        value: "400300,50",
                        modifier: "EUR"
                        } 
                        

                        where:

                        • type indicates the data type, currency.

                        • value indicates the numeric value of the currency. The currency symbol is not part of the value. The value includes the decimal separator, which is determined according to the user’s locale. The value does not contain a thousands separator. In this example, the user's locale is France, therefore the decimal separator used is the comma.

                        • modifier indicates the international three-letter currency code.

                          Number Formats

                          All number formats (NUMBER, INTEGER and PERCENTAGE) for the Oracle CRM On Demand REST API are displayed in the following format:

                          <FieldName> : <Value>
                          

                          The value element includes the decimal separator, which is determined according to the user’s locale. The value does not contains a thousands separator.

                            REST API Request Rate Limits

                            The Oracle CRM On Demand’s REST API resources can be shared by multiple users. Oracle CRM On Demand limits the number of REST API requests that a user can simultaneously execute during a defined time period. The REST Request Rate Limit is 30 requests for each minute.

                            When a user's session is established for the first time or re-established after a session expires or a session is ended by the user signing out, the REST request rate count starts at zero, and it increments by one with each REST request made. The count returns to zero at the end of each defined time period, which is one minute and is not a rolling time period.

                            If the rate limit is exceeded, then the following error message is provided in response to subsequent REST API requests:

                            The maximum rate of requests was exceeded. A maximum of 30 requests per minute is 
                            allowed.
                            

                            Error Response Format

                            Oracle CRM On Demand REST API responses indicating an error or warning are represented by a proper response HTTP status code, such as 404. For more information about HTTP status codes, see Standard HTTP Status Codes.

                            Additionally, a response body is provided containing additional information about the error. The following is an example of the Oracle CRM On Demand Rest API error format:

                            "Error": [
                            {
                             "problemType": "https://support.oracle.com/epmos/faces/DocumentDisplay?id=1802485.1",
                             "title": "The value entered in field %2 of buscomp %3 does not match any value in the bounded pick list%1.",
                             "httpStatus": 400,
                             "detail": "The value entered in field AccountType of buscomp Account does not match any value in the bounded pick list PickList Account Type.(SBL-DAT-00225)",
                             "problemInstance":"urn:ocrmod:/OnDemand/user/Rest/latest/Accounts",
                             "errorCode": "SBL-DAT-00225",
                             "OCRMODErrorDetail": {
                             "Parameters":["PickList Account Type", "AccountType", "Account"]
                             }
                            }] 
                            

                            where:

                            • problemType indicates the location for help about troubleshooting.

                            • title indicates the error message before substituting variables.

                            • httpStatus indicates the HTTP status code.

                            • detail indicates the error message after substituting variables.

                            • problemInstance indicates the URL that generated the error.

                            • errorCode indicates the error code.

                            • OCRMODErrorDetail indicates application-specific details about the error.

                            • Parameters indicates the variables that are used in the error message substitution.

                            Standard HTTP Status Codes

                            Oracle CRM On Demand REST API uses standard HTTP status codes to indicate the success or failure of API calls. When an error occurs or when a response is successful, the response header contains an HTTP code, and the response body usually contains a message accompanying the HTTP response code with additional information about the error. For additional information about Oracle CRM On Demand API error formats, see Error Response Format.

                            The following table contains the standard HTTP status codes used by the Oracle CRM On Demand REST API.

                            Table Standard HTTP Status Codes and Errors Messages

                            HTTP Code Error Message Description

                            200

                            OK

                            The request successfully executed, and the response has content.

                            201

                            Created

                            The resource was successfully created and the response contains the created resource.

                            204

                            No Content

                            The request successfully executed, but content is not available. For example, the content was deleted.

                            302

                            Found

                            The requested resource resides temporarily under a different URL. The response includes redirection to the correct URL.

                            304

                            Not Modified

                            The resource was not modified.

                            400

                            Bad Request

                            The server could not interpret the request.

                            401

                            Unauthorized

                            The request did not have valid authorization credentials.

                            403

                            Forbidden

                            The request has been refused because of insufficient privileges. Verify that the signed-in user has the appropriate privileges.

                            404

                            Not Found

                            The requested resource was not found because of an invalid object name.

                            405

                            Not Allowed

                            The request is not allowed.

                            406

                            Not Acceptable

                            The resource identified by the request is capable of generating only response entities that have content characteristics that are not acceptable according to the accept headers sent in the request.

                            415

                            Unsupported Media Type

                            The data format of the request body, specified in the Content-Type header, is not supported by the targeted resource.

                            500

                            Internal Server Error

                            The server encountered an unexpected error, preventing it from fulfilling the request.