Developer API

The Developer API is an interface for integrating third-party applications with our unique image processing service.

The API can be used to:

When you add images to the processing queue you can define a URL for the Webhook. The Webhook is a simple ”image-has-been-processed”-notification via HTTP POST containing the URL to download image.

Getting Started

When connecting to Remove The Background™ you need an API Key. If you don’t already have an API Key, please sign up for an account (the API Key can be found under Account Settings).

The API Key is used to identify both a customer (ContactAPIkey) and a developer/partner (DeveloperAPIkey). For testing purposes you can use your API Key as both ContactAPIkey and DeveloperAPIkey. The DeveloperAPIkey is used for Resellers and Developer Partners to receive discounts when placing orders.

The Application Secret Code is used to encode/decode the information that we send to you. You can found it right below your API key. If you create a new contact account, this account will have itself API Key and Application Secret Code.

SOAP API

This API is also available in a SOAP version. Click here to go to SOAP service description, or you may like to have HTTPS SOAP API version.

POST Template

Create new template. A template is a set of instructions on how the images should be processed.
POST payload has the parameters as JSON collection.

URL: http://api.removethebackground.com/REST.svc/Template/
OR: https://api.removethebackground.com/REST.svc/Template/
Method: POST
Requires Authentication: false

ParameterRequiredDetails
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
templateNametrueTemplate name. Accept values: A-Z, a-z, 0-9, () and space
templateOutputFormattrueImage output format. Accept values: JPG, JPEG, TIF, TIFF, PNG, PSD
deliveryTimeInHourtrueDelivery time. Accept values: 168, 72, 24
backgroundTypetrueBackground type
0: No background removal
1: Background filled with color; backgroundColor will be required.
2: Transparent background; fileType cannot be JPG/JPEG.
3: Vertical gradient filled background; backgroundColor and backgroundVerticalGradientColor will be required.
backgroundColorfalseHexadecimal number in [000000, FFFFFF]
backgroundVerticalGradientColorfalseHexadecimal number in [000000, FFFFFF]
resizeTypefalseResize type
0: Keep original canvas size (Default)
1: Canvas aspect ratio
2: Fixed width / height
3: Min max only
resizeUnitfalseResize unit, will be ignore if Resize type is ‘Canvas aspect ratio’
0: pixel (Default)
1: milimet
2: inch
resizeHeightfalseImage height after resize
resizeWidthfalseImage width after resize
resizeMinSizefalseImage minimum size for both dimensions
resizeMaxSizefalseImage maximum size for both dimensions
marginTypefalseMargin type
0: Margins not set (Default)
1: Margins in percent
2: Margins in pixels
marginTopfalseTop margin
marginBottomfalseBottom margin
marginLeftfalseLeft margin
marginRightfalseRight margin
marginVerticalAlignmentfalseHow to vertically align if object does not fill canvas
1: Top
2: Center (Default)
3: Bottom
shadowTypefalseShadow type
0: No shadow (default)
1: Keep original shadow
2: Drop shadow
isKeptMannequinfalseKeep the Mannequin or not, accept values: “true”, “false”
isKeptModelfalseKeep the Model or not, accept values: “true”, “false”

Example of payload POST:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "contactEmail": "john @ removethebackground.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "templateName":"My_First_Template",   
    "templateOutputFormat":"JPG",   
    "deliveryTimeInHour":"72",   
    "backgroundType":"1",   
    "backgroundColor":"FFFFFF",   
    "backgroundVerticalGradientColor":"",   
    "resizeType":"1",   
    "resizeUnit":"",   
    "resizeHeight":"4",   
    "resizeWidth":"3",   
    "resizeMinSize":"",   
    "resizeMaxSize":"",   
    "marginType":"2",   
    "marginTop":"10",   
    "marginBottom":"10",   
    "marginLeft":"15",   
    "marginRight":"15",   
    "marginVerticalAlignment":"",   
    "shadowType":""
    "isKeptMannequin":"false"
    "isKeptModel":"false"
}

XML Response:

1
2
3
4
5
6
7
8
9
10
<NewTemplateResponse>
    <Message>Success</Message>
    <ErrorCode>NoError</ErrorCode>
    <TemplateId>2017982</TemplateId>
    <Price>
        <Amount>0.95</Amount>
        <Currency>USD</Currency>
        <CurrencyId>1</CurrencyId>
    </Price>
</NewTemplateResponse>

 

Test Form: POST Template

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
templateName:
templateOutputFormat:
deliveryTimeInHour:
backgroundType:
backgroundColor:
backgroundVerticalGradientColor:
resizeType:
resizeUnit:
resizeHeight:
resizeWidth:
resizeMinSize:
resizeMaxSize:
marginType:
marginTop:
marginBottom:
marginLeft:
marginRight:
marginVerticalAlignment:
shadowType:
isKeptMannequin:
isKeptModel:
JSON Data:
Server response:

GET Template

Retrieves a template detail.

URL: http://api.removethebackground.com/REST.svc/Template/{templateId}/
OR: https://api.removethebackground.com/REST.svc/Template/{templateId}/
Method: GET
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue
templateIdtrue

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<TemplateSpecResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message>Success</Message>
    <Template>
        <BackgroundColor>ffffff</BackgroundColor>
        <BackgroundType>1</BackgroundType>
        <BackgroundVerticalGradientColor/>
        <CallbackFtp i:nil="true"/>
        <CallbackUrl/>
        <CreatedDate>2013-01-02</CreatedDate>
        <DeliveryTimeInHours>168</DeliveryTimeInHours>
        <Id>2018588</Id>
        <IsDeleted>false</IsDeleted>
        <MarginBottom>10</MarginBottom>
        <MarginLeft>10</MarginLeft>
        <MarginRight>10</MarginRight>
        <MarginTop>10</MarginTop>
        <MarginType>2</MarginType>
        <ModifiedDate>2013-01-02</ModifiedDate>
        <Name>Amazon Default Template</Name>
        <OutputFormat>JPG</OutputFormat>
        <Price>
            <a:Amount>0.95</a:Amount>
            <a:Currency>USD</a:Currency>
            <a:CurrencyId>1</a:CurrencyId>
        </Price>
        <ResizeHeight>0</ResizeHeight>
        <ResizeMaxSize>3000</ResizeMaxSize>
        <ResizeMinSize>1000</ResizeMinSize>
        <ResizeType>5</ResizeType>
        <ResizeUnit>0</ResizeUnit>
        <ResizeWidth>0</ResizeWidth>
        <ShadowType i:nil="true"/>
        <VerticalAlignment i:nil="true"/>
    </Template>
</TemplateSpecResponse>

Test Form: GET Template

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
templateId:

GET Templates

Retrieves a list of templates.

URL: http://api.removethebackground.com/REST.svc/Templates/
OR: https://api.removethebackground.com/REST.svc/Templates/
Method: GET
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<TemplatesResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <Templates>
    <Template>
      <Prices>
        <Price>
          <Amount>0.95</Amount>
          <Currency>USD</Currency>
          <CurrencyId>1</CurrencyId>
        </Price>
      </Prices>
      <TemplateId>2000045</TemplateId>
      <TemplateName>T-shirts</TemplateName>
      <IsCombinedImages>false</IsCombinedImages>
    </Template>
  </Templates>
</TemplatesResponse>

Test Form: GET Templates

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:

POST Image

POST payload has the parameters as JSON collection.

URL: http://api.removethebackground.com/REST.svc/Image/
OR: https://api.removethebackground.com/REST.svc/Image/
Method: POST
Requires Authentication: false

ParameterRequiredDetails
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
developerAPIkeyfalseThe API key of the developer/partner. Can be the same as contactAPIkey
templateIdfalseUse GetTemplates to find templateID
imageURLtrueThe source URL of image
imageURL2falseThe source URL of 2nd image (combining images)
imageURL3falseThe source URL of 3rd image (combining images)
imageURL4falseThe source URL of 4th image (combining images)
imageURL5falseThe source URL of 5th image (combining images)
imageRequestedDeliveryTimeInHoursfalseOverwrites template delivery time.
imageCallbackURLfalseWebhook callback URL when image is processed
customerImageIdfalseImageID at the customer side. You can use it as image identity
productIdfalseAll images with the same ProductID will be collected into a single package, and we can take care the consistent quality of all images in this package.

Example of payload POST:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "contactEmail": "john @ removethebackground.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "developerAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "templateId": "2000045",
    "imageURL2": "",
    "imageURL3": "",
    "imageURL4": "",
    "imageURL5": "",
    "imageRequestedDeliveryTimeInHours": "24",
    "imageCallbackURL": "http://www.mydomain.com/callback-url.php",
    "customerImageId": "12345",
    "productId": "Crying Baby Tee 066"
}

XML Response:

1
2
3
4
5
6
7
<AddImageResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <ImageTicket>a37a1f55-7cd4-4474-db19-ac03e85538a7</ImageTicket>
  <IsTrial>false</IsTrial>
  <CustomerImageId>12345</CustomerImageId>
</AddImageResponse>

 

Test Form: POST Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
developerAPIkey:
templateId:
imageURL:
imageURL2:
imageURL3:
imageURL4:
imageURL5:
imageRequestedDeliveryTimeInHours:
imageCallbackURL:
customerImageId:
productId:
JSON Data:
Server response:

DELETE Image

DELETE payload has the parameters as JSON collection. Cannot delete an in-production image.

URL: http://api.removethebackground.com/REST.svc/Image/{imageTicket}/
OR: https://api.removethebackground.com/REST.svc/Image/{imageTicket}/
Method: DELETE
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue
imageTickettrue. If you gonna using customerImageId, set it is “nonticket”
customerImageIdfalse

Example of payload DELETE:

1
2
3
4
5
{
  "contactEmail": "john @ removethebackground.com",
  "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
  "imageTicket": "8de624ab-593b-409d-8324-eb4890c4b867"
}
1
2
3
4
5
6
{
  "contactEmail": "john @ removethebackground.com",
  "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
  "imageTicket": "nonticket",
  "customerImageId": "12345"
}

XML Response:

1
2
3
4
<DeleteImageResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message>Image was deleted</Message>
</DeleteImageResponse>

 

Test Form: DELETE Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:
JSON Data:
Server response:

GET Status

Get the status of image production.

URL: http://api.removethebackground.com/REST.svc/Image/{imageTicket}/
OR: https://api.removethebackground.com/REST.svc/Image/{imageTicket}/
Method: GET
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue
imageTickettrue. If you gonna using customerImageId, set it is “nonticket”
customerImageIdfalse

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<ImageStatusResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <ImageStatus>
    <FinalImagesURL>
      <string>1000003/2000000/final/myimage.jpg</string>
    </FinalImagesURL>
    <ImageTicket>33979dfe-5ea7-44ea-b3dd-7fde33bc37e9</ImageTicket>
    <StatusId>80</StatusId>
    <StatusName>Delivered</StatusName>
    <IsPaid>false</IsPaid>
    <ThumbnailImageURL>1000003/2000000/thumbnail/myimage.jpg</ThumbnailImageURL>
    <CustomerImageId />
    <ProductId />
  </ImageStatus>
</ImageStatusResponse>
 

Test Form: GET Status

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:

GET Images List

Get a list of images.

URL: http://api.removethebackground.com/REST.svc/Images/
OR: https://api.removethebackground.com/REST.svc/Images/
Method: GET
Requires Authentication: false

ParameterRequiredDetail
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
imageStatusfalseThe image status. Refer to table “Image status explanation” for more detailed.
excludeImageStatusfalseThe image status to exclude. Refer to table “Image status explanation” for more detailed.
productIdfalseThe ProductID. See POST Image for more detailed.
fromDatefalseImage created date, lower bound included.
toDatefalseImage created date, upper bound included.
pagefalseThe page number. Default value is 1.
imagesPerPagefalseNumber of images per page. Default value is 10, maximum value is 100.
sortByfalseThe field name that result will be sort by. Accept values: “id”, “date”, “status”.
isDescendingfalseThe sort order is descending or not, accept values: “true”, “false”.

Image status explanation:

Image statusDetail
0Deleted by user
10New images
12New images – download failed
20Deprecated! New images – waiting for payment
30Ready for production
40Returned for production (by you)
60In production
62Assigned to editor
64Downloaded by editor
66Quality Assurance
70Production finished – ready for download
72Production finished – 1st delivery attempt failed
74Production finished – 2nd delivery attempt failed
76Production finished – 3rd delivery attempt failed
78Production finished – Delivery failed
80Delivered
90Rejected by Remove The Background
95Awaiting your reply
100Closed
999Deleted by cleanup service

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<ImagesListResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <Images>
    <ImageStatus>
      <FinalImagesURL>
        <string>1000003/2000000/final/myimage1.jpg</string>
      </FinalImagesURL>
      <ImageTicket>0da2bbe9-4cf4-4c16-8e46-52048836a01b</ImageTicket>
      <StatusId>70</StatusId>
      <StatusName>Production Finished</StatusName>
      <IsPaid>false</IsPaid>
      <ThumbnailImageURL>1000003/2000000/thumbnail/myimage1.jpg</ThumbnailImageURL>
      <CustomerImageId />
      <ProductId />
    </ImageStatus>
    <ImageStatus>
      <FinalImagesURL>
        <string>1000003/2000000/final/myimage2.jpg</string>
      </FinalImagesURL>
      <ImageTicket>fb4751e1-4475-4bf8-a21f-1c0d8b1bb52d</ImageTicket>
      <StatusId>80</StatusId>
      <StatusName>Delivered</StatusName>
      <IsPaid>false</IsPaid>
      <ThumbnailImageURL>1000003/2000000/thumbnail/myimage2.jpg</ThumbnailImageURL>
      <CustomerImageId />
      <ProductId />
    </ImageStatus>
  </Images>
</ImagesListResponse>

Test Form: GET Images List

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageStatus:
fromDate:
toDate:
page:
imagesPerPage:
excludeImageStatus:
sortBy:
isDescending:

GET Count Images

Count number of images.

URL: http://api.removethebackground.com/REST.svc/Images/Count/
OR: https://api.removethebackground.com/REST.svc/Images/Count/
Method: GET
Requires Authentication: false

ParameterRequiredDetail
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
imageStatusfalseThe image status. Refer to table “Image status explanation” for more detailed.
fromDatefalseImage created date, lower bound included.
toDatefalseImage created date, upper bound included.

XML Response:

1
2
3
4
5
<ImagesCountResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <ImagesCount>315</ImagesCount>
</ImagesCountResponse>

Test Form: COUNT Images

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageStatus:
fromDate:
toDate:

GET ProductId-s List

Get a list of ProductIds.

URL: http://api.removethebackground.com/REST.svc/ProductIds/
OR: https://api.removethebackground.com/REST.svc/ProductIds/
Method: GET
Requires Authentication: false

ParameterRequiredDetail
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
pagefalseThe page number. Default value is 1.
productIdsPerPagefalseNumber of productId-s per page. Default value is 10, maximum value is 100.

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<ProductIdsListResponse>
    <Message/>
    <ErrorCode>NoError</ErrorCode>
    <ProductIds>
        <ProductIdStatistic>
            <ProductId>test product 01</ProductId>
            <DoneCount>102</DoneCount>
            <TodoCount>5</TodoCount>
        </ProductIdStatistic>
        <ProductIdStatistic>
            <ProductId>test product 02</ProductId>
            <DoneCount>27</DoneCount>
            <TodoCount>0</TodoCount>
        </ProductIdStatistic>
    </ProductIds>
</ProductIdsListResponse>

Test Form: GET ProductId-s List

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
page:
productIdsPerPage:

REJECT Image

REJECT payload has the parameters as JSON collection. Cannot reject a not yet finished image.

URL: http://api.removethebackground.com/REST.svc/Image/Reject/{imageTicket}/
OR: https://api.removethebackground.com/REST.svc/Image/Reject/{imageTicket}/
Method: PUT
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue
imageTickettrue. If you gonna using customerImageId, set it is “nonticket”
customerImageIdfalse
commentfalse

Example of payload REJECT:

1
2
3
4
5
6
{
  "contactEmail": "john @ removethebackground.com",
  "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
  "imageTicket": "8de624ab-593b-409d-8324-eb4890c4b867",
  "comment": "Free text comment"
}
1
2
3
4
5
6
7
{
  "contactEmail": "john @ removethebackground.com",
  "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
  "imageTicket": "nonticket",
  "customerImageId": "12345"
  "comment": "Free text comment"
}

XML Response:

1
2
3
4
<RejectImageResponse >
  <ErrorCode>NoError</ErrorCode>
  <Message>Image was rejected.</Message>
</RejectImageResponse >

 

Test Form: REJECT Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:
comment:
JSON Data:
Server response:

POST Contact

POST payload has the parameters as JSON collection.

URL: http://api.removethebackground.com/REST.svc/Contact/
OR: https://api.removethebackground.com/REST.svc/Contact/
Method: POST
Requires Authentication: false

ParameterRequiredDetails
developerEmailtrueThe email address of the developer/partner
developerAPIkeytrueThe API key of the developer/partner
contactEmailtrueEmail of the new contact
contactNametrueName of the new contact
countryCodetrueThe ISO 3166-1 alpha-2 two-letter country code
contactAddress1false
contactAddress2false
contactPhonefalse
contactCityfalse
contactStatefalse
contactZipCodefalse

Example of payload POST:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "developerEmail":"john @ removethebackground.com",
    "developerAPIkey":"44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "contactEmail":"my_new_customer @ domain.com",
    "contactName":"My First Customer",
    "countryCode":"US",
    "contactAddress1":"",
    "contactAddress2":"",
    "contactPhone":"",
    "contactCity":"",
    "contactState":"",
    "contactZipCode":""
}

XML Response:

1
2
3
4
5
6
<NewContactResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message>Success</Message>
    <ContactAPIkey>5ea1a104-f31f-4de1-b7f8-e4444e38e32a</ContactAPIkey>
    <ContactEmail>my_new_customer @ domain.com</ContactEmail>
</NewContactResponse>

 

Test Form: POST Contact

Enter your information in the form below and get the server response.

developerEmail:
developerAPIkey:
contactEmail:
contactName:
countryCode:
contactAddress1:
contactAddress2:
contactPhone:
contactCity:
contactState:
contactZipCode:
JSON Data:
Server response:

GET Contact

Retrieves your contact information, include email, contact person, credit line and account balance.

URL: http://api.removethebackground.com/REST.svc/Contact/
OR: https://api.removethebackground.com/REST.svc/Contact/
Method: GET
Requires Authentication: false

ParameterRequired
contactEmailtrue
contactAPIkeytrue

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<ContactResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message/>
  <Contact>
    <ContactAccountBalance>
      <Amount>81.05</Amount>
      <Currency>USD</Currency>
      <CurrencyId>1</CurrencyId>
    </ContactAccountBalance>
    <ContactCompany>Remove The Background</ContactCompany>
    <ContactDaysOfCredit>10000</ContactDaysOfCredit>
    <ContactEmail>john @ removethebackground.com</ContactEmail>
    <ContactPerson>John</ContactPerson>
    <NumberOfTrialImages>3</NumberOfTrialImages>
  </Contact>
</ContactResponse>

Test Form: GET Contact

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:

GET Invoices

Retrieves your invoices list.

URL: http://api.removethebackground.com/REST.svc/Invoices/
OR: https://api.removethebackground.com/REST.svc/Invoices/
Method: GET
Requires Authentication: false

ParameterRequiredDetail
contactEmailtrueThe email address of the customer
contactAPIkeytrueThe API key of the customer
fromDatefalseInvoice created date, lower bound included.
toDatefalseInvoice created date, upper bound included.
pagefalseThe page number. Default value is 1. Max 50 invoices per page.
returnUrlfalseThe URL where customer will be redirected after finish payment

XML Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<InvoiceListResponse>
  <Message/>
  <ErrorCode>NoError</ErrorCode>
  <Invoices>
    <Invoice>
      <InvoiceId>INV-1315</InvoiceId>
      <CreatedDate>2012-12-31</CreatedDate>
      <AmountDue>0.00</AmountDue>
      <IsPaid>true</IsPaid>
      <PaymentUrl />
      <InvoiceUrl>/DownloadInvoice?invoiceNumber=INV-1315</InvoiceUrl>
    </Invoice>
    <Invoice>
      <InvoiceId>INV-1289</InvoiceId>
      <CreatedDate>2012-12-26</CreatedDate>
      <AmountDue>105.00</AmountDue>
      <IsPaid>false</IsPaid>
      <PaymentUrl>/Transactions?key=1234567890&returnUrl=http://test.com/testurl</PaymentUrl>
      <InvoiceUrl>/DownloadInvoice?invoiceNumber=INV-1289</InvoiceUrl>
    </Invoice>
  </Invoices>
</InvoiceListResponse>

Test Form: GET Invoices

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
fromDate:
toDate:
page:
returnUrl:

Webhook

The Remove The Background Webhook will notify you when the image has been processed. The Webhook will POST data to the Image Callback URL specified and expects a 200 HTTP status code. The Webhook will try to deliver the image 4 times with different time intervals:

First try: Right after the image finished
Second try: +5 minutes later
Third try: +1 hour later
Fourth try: +5 hours later

The ImageCallbackURL has higher priority than TemplateCallbackURL. If image has no ImageCallbackURL then we will use TemplateCallbackURL.

URL: As specified
Method: POST
Requires Authentication: false

ParameterRequiredDetails
imageTickettrueThe ticketID of the processed image
processedImageURLtrueThe URL to download image from remote server
templateIdtrueIdentify the templateId that the finished image version belong to. Useful if your images has more than one output versions. (NEW)
customerImageIdfalseIf you POST an image with a customerImageId, the webhook will return it back as an additional parameter. This will help you to identify the image using your customerImageId. Of course you still can use the imageTicket as usual. (NEW)

Test form: Webhook

Here you can make a test request to your call back page.

contactAPIkey:
Call Back URL:

Verify Webhook

Our webhooks can be verified that they came from RemoveTheBackground by calculating a digital signature.

Along with the data sent in the request, each Webhook request includes

  • A HTTP_X_RTB_PARTNER_HMAC_SHA256 header, encoded using developer/partner application secret code. Log in into our website to get your application secret code, right below your API key. This header is only available if you POST image with a developerAPIkey.
  • A HTTP_X_RTB_CUSTOMER_HMAC_SHA256 header, encoded using customer application secret code. To use this, you may have customer input their application secret code. This header always available.

To verify that the request came from RemoveTheBackground, compute the HMAC digest according to the following algorithm and compare it to the value in the header. If they match, you can be sure that the Webhook was sent from RemoveTheBackground and the data has not been compromised.

Below is a simple example in C# using .NET framework of how one might verify a webhook request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
public partial class CallBack : System.Web.UI.Page
{
    private const string appCode = "my_application_secret_code";
    protected void Page_Load(object sender, EventArgs e)
    {
        string hmacHeader = Request.Headers["HTTP_X_RTB_PARTNER_HMAC_SHA256"];
        byte[] data = Request.BinaryRead(Request.ContentLength);
        if (!VerifyWebhook(appCode, data, hmacHeader))
        {
            // Write error log
        }
    }
    private bool VerifyWebhook(string key, byte[] data, string hmacHeader)
    {
        using (HMACSHA256 hmac = new HMACSHA256(GetBytes(key)))
        {
            string calculatedHmac = Convert.ToBase64String(hmac.ComputeHash(data));
            return hmacHeader == calculatedHmac;
        }
    }
    private static byte[] GetBytes(string str)
    {
        byte[] bytes = new byte[str.Length * sizeof(char)];
        System.Buffer.BlockCopy(str.ToCharArray(), 0, bytes, 0, bytes.Length);
        return bytes;
    }
}

And here’s a PHP version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?php
define('APP_CODE', 'my_application_secret_code');
function verify_webhook($data, $hmac_header)
{
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, APP_CODE, true));
  return ($hmac_header == $calculated_hmac);
}
$hmac_header = $_SERVER['HTTP_X_RTB_PARTNER_HMAC_SHA256'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);
error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result
?>