POST /elements/{keyOrId}/instances

POST /elements/{keyOrId}/instances

Create a new authenticated adapter instance specified by adapter key or adapter id.

Alternatively, you can create an adapter instance with a POST /instances request.

Path Parameters

keyOrIdThe adapter key is a unique alphanumeric identifier for the adapter, while the adapter id is a unique numeric identifier for the adapter. Replace keyOrId with either identifier.

Request Body Parameters

The body parameters differ based on the authentication type and parameters required by each individual adapter. For specific requirements, see the Authenticate or Create Instance section in the documentation for a specific adapter.  We've provided some default parameters below for our two most common authentication types: Basic and OAuth 2.0.

Basic Authentication Default Parameters

usernameThe user name needed to authenticate an adapter instance with Basic authentication. See the Adapter Documentation's Setup section to identify what value at the provider is used as the username.
passwordThe password needed to authenticate an adapter instance with Basic authentication. See the Adapter Documentation's Setup section to identify what value at the provider is used as the password.
tagsUser-defined tags to further identify or categorize the adapter instance.
nameThe display name of the authenticated adapter instance.

OAuth 2.0 Authentication Default Parameters

providerData.codeThe authorization grant code returned from the API provider in an OAuth 2.0 authentication workflow. Sugar Integrate uses the code to retrieve the OAuth access and refresh tokens from the endpoint.
oauth.api.keyThe API key or client ID obtained by registering your app with the provider. See the Adapter Documentation's Setup section to identify what value at the provider is used as the API key.
oauth.api.secretThe API or client secret obtained by registering your app with the API provider. See the Adapter Documentation's Setup section to identify what value at the provider is used as the API secret.
oauth.callback.urlThe URL where the API provider returns the authorization grant code and also where a user returns after they authorize access.
tagsUser-defined tags to further identify or categorize the adapter instance.
nameThe display name of the authenticated adapter instance.

Response Fields

The table below shows an abbreviated list of response fields.

idThe adapter instance id is a unique numeric identifier for the authenticated adapter instance.
nameThe display name of the authenticated adapter instance.
createdDateThe date and time of the initial authentication of the the adapter instance.
tokenThe adapter instance token returned upon authenticating an adapter instance. You must include the adapter instance token in the Authorization header of requests to the adapter instance.
elementInformation about the adapter.
configurationObject containing the configuration of the adapter.
eventsEnabledIndicates whether events are configured for the instance.
userAn object containing details about the user.

Example Request

The following example requests represent generic requests using Basic and OAuth 2.0 authentication. 

Basic Authentication Example Request

curl -X POST \
  https://api-us.integrate.sugarapps.com/elements/api-v2/elements/insightly/instances \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \
  -d '{
  "configuration": {
    "username": "claudeelements",
    "password": "password"
  },
  "tags": [
    "Docs"
  ],
  "name": "Element Instance Name"
}'

OAuth 2.0 Authentication Example Request


curl -X POST \
  https://api-us.integrate.sugarapps.com/elements/api-v2/elements/onedrivev2/instances \
  -H 'Authorization: User zn96SWr/RjPPWztl+oQcFkT0mbKPpW7hEvPkYcRy6xM=, Organization 4c193728a11e2d03025e29992948b12c' \
  -H 'Content-Type: application/json' \
  -d '{
  "providerData":{  
    "code":"WCT3Ny3QRbA6HDXY "
  },
  "configuration":{  
    "oauth.api.key": "Rand0MAP1-key",
    "oauth.api.secret":"fak3AP1-s3Cr3t",
    "oauth.callback.url":"https://mycoolapp.com"
  },
  "tags":[  
    "Docs"
  ],
  "name":"Element Instance Name"
}
'

Example Response


{  
  "id":477858,
  "name":"New Element",
  "createdDate":"2018-04-11T18:25:46Z",
  "token":"s1GKjbAO37W1UNsBd4GI80RmUPXk/nzTPFmLKwL1Tws=",
  "element":{  },
  "elementId":5993,
  "tags":[  ],
  "provisionInteractions":[  ],
  "valid":true,
  "disabled":false,
  "maxCacheSize":0,
  "cacheTimeToLive":0,
  "configuration":{  },
  "eventsEnabled":false,
  "traceLoggingEnabled":false,
  "cachingEnabled":false,
  "externalAuthentication":"none",
  "user":{  }
}