Connect API Overview

Overview

All of the data elements and actions related to the fulfillment management module are available through the API that could be used interchangeably with the manual fulfillment through the User Interface as summarized with the following diagram:


And makes the following operations available to the vendor.

#
API Method Name
1
Get Requests List - GET /requests
2
Get Request Details - GET /requests/{id}
3
Modify Request Data - PUT /requests/{id}
4
Change Request Status - POST /requests/{id}/{status}

Note that all of the API calls described in this article follow common Data Format Conventions.


1. Get Requests List - GET /requests

Resource
/requests
Method
GET
Header
Authorization: ApiKey <key_id>:<key_secret>
Filter(s)
status, created, asset_id, product_id
Default Filter(s)
status='pending'
Ordering
-
Default Ordering
created (ascending)
Limit
-
Default limit
1000


Response body:

Content-Type: application/json

[ request_obj1,
  request_obj2,
  request_obj3
]

Recommended Polling Period

Automation script would typically poll for changed data periodically. Our recommendation is to process fulfillment queue every 2~5 minutes, i.e. not more often than every 2 minutes (to reduce load on the API queue) and at least as often as every 5 minutes (to limit order completion time). Though this polling frequency depends on business requirements for how quickly changes in requests queue need to be reflected in your systems and are generally dependent on the SLAs defined by the Provider.


2. Get Request Details - GET /requests/{id}

Resource
/requests/{id}
Method
GET
Header
Authorization: ApiKey <key_id>:<key_secret>
Filter(s)
-
Default Filter(s)
-
Ordering
-
Default Ordering
-
Limit
-
Default limit
-


Response body:

Content-Type: application/json

{
    "id": "PR-9861-7949-8492",
    "type": "purchase",
    "created": "2018-06-04T13:19:10.102670+00:00",
    "updated": "2018-06-04T13:19:10.102670+00:00",
    "status": "pending",
 
    "asset": {
 
        "id": "AS-9861-7949-8492",
        "external_id": "12435 #OSA Subscription Id",
 
        "product": {
            "id": "CN-9861-7949-8492",
            "name": "Fallball Awesone"
        },
 
        "connection": {
            "id": "CT-9861-7949-8492",
            "type": "production",
 
            "provider": {
                "name": "Ingram Micro Prod DA",
                "id": "PA-9861-7949-849"
            },
 
            "vendor": {
                "name": "Large Largo and Co",
                "id": "VA-9861-7949-849"
            }
        },
 
        "items": [{
                "id": "SKU-9861-7949-8492-0001",
                "mpn": "TEAM-ST3L2TAC1M",
                "quantity": "3",
                "old_quantity": ""
            },
            {
                "id": "SKU-9861-7949-8492-0002",
                "mpn": "USR-FFFAC1M",
                "quantity": "1",
                "old_quantity": ""
            }
        ],
 
        "params": [{
            "id": "PM-9861-7949-8492-0001 #AUTOGEN #PRODUCT",
            "name": "Secondary email",
            "description": "This is a backup email for emergency",
            "value": "daniel.lark@gmail.com",
            "value_error": "This address is already used. Try another.",
            "value_choices": ""
        }],
 
        "tiers": {
            "customer": {
                "id": "CS-9861-7949-8492",
                "external_id": "12435 #OSA Account Id",
                "account_name": "string",
                "contact_info": {
                    "address_line1": "Yalı Mahallesi",
                    "address_line2": "",
                    "city": "Erdek",
                    "state": "string",
                    "postal_code": "10500",
                    "country": "tr",
                    "contact": {
                        "first_name": "Quickstart",
                        "last_name": "Long Running Operation",
                        "email": "qlro@softcom.com",
                        "phone_number": {
                            "country_code": "+90",
                            "area_code": "546",
                            "phone_number": "6317546",
                            "extension": ""
                        }
                    }
 
                },
 
                "tier1": {
                    "id": "RS-9861-7949-8492",
                    "external_id": "12435 #OSA Account Id",
                    "account_name": "string",
                    "contact_info": { ...
                    }
                },
 
                "tier2": {
                    "id": "RS-9861-7949-8492",
                    "external_id": "12435 #OSA Account Id",
                    "account_name": "string",
                    "contact_info": { ...
                    }
                },
 
                "marketplace": {
                    "id": "MP-9861-7949-8492",
                    "name": "Ingram Micro Cloud United",
                    "external_id": "12435 #OSA Account Id",
                    "account_name": "string",
                    "contact_info": { ...
                    }
                }
            }
        }

3. Modify Request Data - PUT /requests/{id}

Resource
/requests/{id}
Method
PUT (Partial Update)
Header
Authorization: ApiKey <key_id>:<key_secret>
Filter(s)
-
Default Filter(s)
-
Ordering
-
Default Ordering
-
Limit
-
Default limit
-

Request body:

Content-Type: application/json

{
    "asset": {
       "params": [
            {
                "id": "PM-9861-7949-8492-0001",
                "name": "Secondary email",
                "description": "This is a backup email for emergency",
                "value": "daniel.lark@example.com", // MODIFICATION ALLOWED
                "value_error": "Invalid address. Try another.", // MODIFICATION ALLOWED
                "value_choices": []
            },

           {
                "id": "PM-9861-7949-8492-0002",
                "name": "Secondary email",
                "description": "This is a backup email for emergency",
                "value": "daniel.lark@example.com", // MODIFICATION ALLOWED
                "value_error": "Invalid address. Try another.", // MODIFICATION ALLOWED
                "value_choices": []
            }
        ]
    }
}


Response body:

Content-Type: application/json

[ request_obj1,
  request_obj2,
  request_obj3
]

4. Change Request Status - POST /requests/{id}/{status}

Resource
/requests/{id}/{new_status}
Method
POST
Header
Authorization: ApiKey <key_id>:<key_secret>
Filter(s)
-
Default Filter(s)
-
Ordering
-
Default Ordering
-
Limit
-
Default limit
-


4a. Status Approve

Resource
/requests/{id}/approve
Method
POST
Header
Authorization: ApiKey <key_id>:<key_secret>


Request body with the Activation Template ID:

Content-Type: application/json

{
   "template_id": "{activation_template_id}"
}


Request body with the Raw Markdown:

Content-Type: application/json

{
   "activation_tile": "markdown text up to 4096 symbols"
}


4b. Status Fail

Resource
/requests/{id}/fail
Method
POST
Header
Authorization: ApiKey <key_id>:<key_secret>


Request body:

Content-Type: application/json

{
   "reason": "markdown string up to 4096 symbols"
}


4c. Status Inquire

Resource
/requests/{id}/inquire
Method
POST
Header
Authorization: ApiKey <key_id>:<key_secret>


Request body:

Content-Type: application/json

{}


Response body:

Content-Type: application/json

{ request_obj }


4d. Status → Pend

Resource
/requests/{id}/pend
Method
POST
Header
Authorization: ApiKey <key_id>:<key_secret>


Request body:

Content-Type: application/json

{}


Response body:

Content-Type: application/json

{ request_obj }

Request Status Transitions


Where supported and unsupported transitions matrix is summarized below:


1. To NewTo Inquiring
To PendingTo ApprovedTo Failed
From New-SYSTEMSYSTEM-SYSTEM
From Inquiring--SUPPORTEDSUPPORTED
SUPPORTED
From Pending-SUPPORTED
-SUPPORTED
SUPPORTED
From Approved-----
From Failed-----


Supported (valid) transitions:

  1. new → inquiring (automatic transition by system)
  2. new → pending (automatic transition by system)
  3. new → failed (automatic transition by system)
  4. pending → inquiring
  5. pending → failed
  6. pending → approved
  7. inquiring → failed
  8. inquiring → approved
  9. inquiring → pending


Unsupported (invalid) transitions:

  1. new new
  2. new → approved
  3. inquiring new

  4. inquiring inquiring

  5. pending new

  6. pending pending

  7. approved → new

  8. approved → inquiring

  9. approved → pending

  10. approved → approved

  11. approved → failed

  12. failed → new
  13. failed → inquiring

  14. failed → pending

  15. failed → approved

  16. failed → failed