Documentation

v1.0.0

Getting started

First things first, you’ll need to request an API key so we can understand what you want to build and ensure we can make it happen.

Authorization

Authorization with 99designs requires the following HTTP headers are forwarded on every request: Api-Key-Id and Api-Key-Secret. The values for theses headers are provided by 99designs.

curl -H "Api-Key-Id:xxx" -H "Api-Key-Secret:xxx" https://api.99designs.com/resources/v1/designers

Briefs

The following API calls are for unauthenticated users and therefore will require that the end user come to 99designs to create an account (or log into an existing one). Each will provide a response with the appropriate URL to allow the end user to do so.

Create a brief

Example request:
curl -X POST https://api.99designs.com/resources/v1/briefs -H "Content-Type:application/json" -d '{
  "category": "product-packaging",
  "title": "Packaging for The Organic Juicy Fruits Company",
  "description": "I need a package designed for a new flavor of organic juice.",
  "profileApproval": false,
  "industry": "accounting",
  "inspirationUrls": [
    "https://example.org/example1",
    "https://example.org/example2"
  ],
  "budget": {
    "value": 10000,
    "currency": "USD"
  },
  "other": "",
  "timeframe": {
    "value": "specific_dates",
    "startDate": "2018-01-20T00:00:00+0500",
    "endDate": "2018-01-20T00:00:00+0500"
  },
  "urls": [
    ""
  ],
  "usage": "Billboards, flyers, and magazines",
  "language": "de"
}'
Body parameters:
category
string

What type of design do you need?

e.g. product-packaging

Values3d-designalbum-cover-designapp-designart-illustrationbanner-ad-designbook-cover-designbook-magazine-designbrand-guidebrand-identity-packbrochure-designbusiness-advertisingbusiness-card-designbuttons-iconscar-truck-van-wrap-designcard-invitation-designcharacter-mascot-designclothing-apparel-designclothing-merchandise-designcup-mug-designcustom-wordpress-themesemail-designfacebook-adfacebook-cover-designflash-animationflash-banner-designicon-button-designillustrationsinfographic-designlanding-page-designlogologo-brand-guidelogo-business-card-designlogo-designlogo-product-packaginglogo-websitemagazine-cover-designmenu-designmerchandise-designmobile-app-designnationbuilderotherother-art-illustrationother-book-magazine-designother-business-advertisingother-clothing-merchandise-designother-designother-design-tasksother-packaging-label-designother-website-app-designpackaging-label-designpodcast-cover-designpostcard-flyer-designposter-designpowerpoint-template-designprezi-designprint-designproduct-label-designproduct-packaging-designquickbooks-form-designsignage-designsocial-media-packsocial-media-page-designsquare-online-storesquarespacestationery-designsticker-designt-shirt-designtattoo-designtwitter-background-designtypesettingtypesetting-with-imageryweb-builderweb-designweb-design-codedwebsite-app-designwix-websitewordpress-theme-designzoom-background-design
title
string

What's the name of your project?

e.g. Packaging for The Organic Juicy Fruits Company

description
string

Describe your project

e.g. I need a package designed for a new flavor of organic juice.

profileApproval
boolean

Can your designer showcase the finished designs in their 99designs portfolio?

industry
string

What industry are you in?

Valuesaccountingagricultureanimalsarchitecturalartattorneyautomotivebarbusinesschildrencleaningcommunicationscommunitycomputerconstructioncosmeticsdatingeducationentertainmentenvironmentfashionfloralfoodgameshomeindustrialinternetlandscapingmedicalotherphotographyphysicalpoliticsrealestatereligiousrestaurantretailsecurityspasportstechnologytravelwedding
inspirationUrls
array

Inspiration on the web

e.g.[ "https://example.org/example1", "https://example.org/example2" ]
budget
object

Client budget

value
integer

budget in cents

e.g. 10000

currency
string

e.g. USD

other
string

Anything else you'd like to share with your designer?

timeframe
object

Project timeframe

value
string

e.g. specific_dates

Valuesforty_eight_hoursone_weektwo_weeksone_monthspecific_datesnot_sure
startDate
string

ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)

e.g. 2018-01-20T00:00:00+0500

endDate
string

ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)

e.g. 2018-01-20T00:00:00+0500

urls
array

Your website and/or social media pages

usage
string

How will your design be used?

e.g. Billboards, flyers, and magazines

language
string
Valuesdeenesfritjanlpt
Example response(s):
201Created brief
{
  "id": "abc123",
  "briefUrl": "99designs.com/briefs/abc123"
}
400Validation error(s)
{
  "errors": [
    {
      "path": "/briefs",
      "message": "Invalid timeframe"
    }
  ]
}

Designers

Search designers

Returns a list of designers that meet certain criteria in order of best match first.
Example request:
curl -X POST https://api.99designs.com/resources/v1/designers -H "Content-Type:application/json" -d '{
  "certifications": [
    ""
  ],
  "category": [
    "3d-design"
  ],
  "industry": [
    "accounting"
  ],
  "language": [
    "de"
  ],
  "designerLevel": [
    "entry"
  ],
  "lastActivity": "online_now",
  "designLimit": 10,
  "keywordQuery": "",
  "pageSize": 30,
  "page": 1,
  "country": [
    "US",
    "AU"
  ]
}'
Body parameters:
certifications
array

Filter designers based on certifications

category
array

Design category (one or more)

Values3d-designalbum-cover-designapp-designart-illustrationbanner-ad-designbook-cover-designbook-magazine-designbrand-guidebrand-identity-packbrochure-designbusiness-advertisingbusiness-card-designbuttons-iconscar-truck-van-wrap-designcard-invitation-designcharacter-mascot-designclothing-apparel-designclothing-merchandise-designcup-mug-designcustom-wordpress-themesemail-designfacebook-adfacebook-cover-designflash-animationflash-banner-designicon-button-designillustrationsinfographic-designlanding-page-designlogologo-brand-guidelogo-business-card-designlogo-designlogo-product-packaginglogo-websitemagazine-cover-designmenu-designmerchandise-designmobile-app-designnationbuilderotherother-art-illustrationother-book-magazine-designother-business-advertisingother-clothing-merchandise-designother-designother-design-tasksother-packaging-label-designother-website-app-designpackaging-label-designpodcast-cover-designpostcard-flyer-designposter-designpowerpoint-template-designprezi-designprint-designproduct-label-designproduct-packaging-designquickbooks-form-designsignage-designsocial-media-packsocial-media-page-designsquare-online-storesquarespacestationery-designsticker-designt-shirt-designtattoo-designtwitter-background-designtypesettingtypesetting-with-imageryweb-builderweb-designweb-design-codedwebsite-app-designwix-websitewordpress-theme-designzoom-background-design
industry
array

Industry (one or more)

Valuesaccountingagricultureanimalsarchitecturalartattorneyautomotivebarbusinesschildrencleaningcommunicationscommunitycomputerconstructioncosmeticsdatingeducationentertainmentenvironmentfashionfloralfoodgameshomeindustrialinternetlandscapingmedicalotherphotographyphysicalpoliticsrealestatereligiousrestaurantretailsecurityspasportstechnologytravelwedding
language
array

Designer language (one or more)

Valuesdeenesfritjanlpt
designerLevel
array

Designer level

Valuesentrymidtop
lastActivity
string

Filter designers based on their last login time

Valuesonline_nowwithin_7_days
designLimit
integer

Maximum number of example designs per designer

e.g. 10

keywordQuery
string

Keyword for filtering results

pageSize
integer

Maximum number of designers to return per page (defaults to 30)

e.g. 30

page
integer

Page of the results

e.g. 1

country
array

Filter designers based on ISO alpha-2 country codes i.e. (US, AU, DE)

e.g.[ "US", "AU" ]
Example response(s):
200An array of designers
{
  "totalPages": 10,
  "totalResults": 100,
  "designers": [
    {
      "id": 1,
      "coverImageUrl": "https://images-platform.99static.com/99designs-profiles/cover-images-v2/123123/123abc.jpg",
      "biography": "Professional brand designer.",
      "avatarUrl": "https://99designs.com/avatars/users/1/128",
      "displayName": "DesignerAllTheThings",
      "lastSeenAt": "2019-01-01T00:00:00Z",
      "designs": [
        {
          "description": "Logo for a cool company",
          "id": 123123,
          "imageUrl": "http://s3.amazonaws.com/projects-files/1/123/456/123abc.png",
          "title": "Cool company",
          "tags": [
            "technology"
          ]
        }
      ],
      "designerLevel": "TOP",
      "expertiseCategories": [
        "logo-design",
        "web-design"
      ],
      "review": {
        "count": 100,
        "rating": 5
      },
      "repeatCount": 20,
      "completedProjectsCount": 50
    }
  ]
}
400Bad input
{
  "message": "An error has occurred"
}

Get designer by ID

Returns a single designer with the given ID.
Example request:
curl -X GET https://api.99designs.com/resources/v1/designers/{designerId}
Path parameters:
designerId
integer

ID of the designer

Example response(s):
200A designer
{
  "id": 1,
  "coverImageUrl": "https://images-platform.99static.com/99designs-profiles/cover-images-v2/123123/123abc.jpg",
  "biography": "Professional brand designer.",
  "avatarUrl": "https://99designs.com/avatars/users/1/128",
  "displayName": "DesignerAllTheThings",
  "lastSeenAt": "2019-01-01T00:00:00Z",
  "designs": [
    {
      "description": "Logo for a cool company",
      "id": 123123,
      "imageUrl": "http://s3.amazonaws.com/projects-files/1/123/456/123abc.png",
      "title": "Cool company",
      "tags": [
        "technology"
      ]
    }
  ],
  "designerLevel": "TOP",
  "expertise": [
    ""
  ],
  "expertiseCategories": [
    "logo-design",
    "web-design"
  ],
  "review": {
    "rating": 5,
    "count": 100
  },
  "reviews": [
    {
      "rating": 5,
      "message": "This was a fantastic designer to work with!",
      "displayName": "EmilyBakes"
    }
  ],
  "country": "AU",
  "repeatCount": 20,
  "responsivenessScore": 92.5,
  "completedProjectsCount": 50,
  "isAvailable": false,
  "workPreferences": {
    "squarespace": [
      "DESIGN"
    ]
  },
  "certifications": [
    ""
  ],
  "isBoosted": false
}
400Bad input
{
  "message": "An error has occurred"
}
404Not found
{
  "message": "An error has occurred"
}

Get designer reviews

Return customer reviews for a given designer
Example request:
curl -X GET https://api.99designs.com/resources/v1/designers/{designerId}/reviews?page=&pageSize=
Path parameters:
designerId
integer

ID of the designer

Query parameters:
page
integer

Page number

pageSize
integer

Page size limit

Example response(s):
200Reviews
{
  "totalPages": 10,
  "totalResults": 100,
  "reviews": [
    {
      "rating": 5,
      "message": "This was a fantastic designer to work with!",
      "displayName": "EmilyBakes"
    }
  ]
}

Get portfolio designs

Get all portfolio designs for a given designer
Example request:
curl -X GET https://api.99designs.com/resources/v1/designers/{designerId}/designs?page=&pageSize=&category=
Path parameters:
designerId
integer

ID of the designer

Query parameters:
page
integer

Page Number

pageSize
integer

Page size limit

category
array

Design category (one or more)

Values3d-designalbum-cover-designapp-designart-illustrationbanner-ad-designbook-cover-designbook-magazine-designbrand-guidebrand-identity-packbrochure-designbusiness-advertisingbusiness-card-designbuttons-iconscar-truck-van-wrap-designcard-invitation-designcharacter-mascot-designclothing-apparel-designclothing-merchandise-designcup-mug-designcustom-wordpress-themesemail-designfacebook-adfacebook-cover-designflash-animationflash-banner-designicon-button-designillustrationsinfographic-designlanding-page-designlogologo-brand-guidelogo-business-card-designlogo-designlogo-product-packaginglogo-websitemagazine-cover-designmenu-designmerchandise-designmobile-app-designnationbuilderotherother-art-illustrationother-book-magazine-designother-business-advertisingother-clothing-merchandise-designother-designother-design-tasksother-packaging-label-designother-website-app-designpackaging-label-designpodcast-cover-designpostcard-flyer-designposter-designpowerpoint-template-designprezi-designprint-designproduct-label-designproduct-packaging-designquickbooks-form-designsignage-designsocial-media-packsocial-media-page-designsquare-online-storesquarespacestationery-designsticker-designt-shirt-designtattoo-designtwitter-background-designtypesettingtypesetting-with-imageryweb-builderweb-designweb-design-codedwebsite-app-designwix-websitewordpress-theme-designzoom-background-design
Example response(s):
200Designs
{
  "totalPages": 10,
  "totalResults": 100,
  "designs": [
    {
      "description": "Logo for a cool company",
      "id": 123123,
      "imageUrl": "http://s3.amazonaws.com/projects-files/1/123/456/123abc.png",
      "title": "Cool company",
      "tags": [
        "technology"
      ]
    }
  ]
}

Coupons

Generate a new partner coupon

Returns a signed partner coupon that can be passed back to 99designs via URL parameter, and a URL based on the campaign ID that can be used directly.
Example request:
curl -X POST https://api.99designs.com/resources/v1/coupons -H "Content-Type:application/json" -d '{
  "aud": "partner-july-2020",
  "sub": "client@example.com",
  "jti": "WP6345789",
  "exp": 0,
  "nbf": 0
}'
Body parameters:
aud
string

Name of the campaign the token relates to. This will be provided by 99designs for your specific campaign.

e.g. partner-july-2020

sub
string

Identify the user for which this token relates to. This can be any identifier the partner wishes to provide. One or both of sub or jit are required.

e.g. client@example.com

jti
string

Identify a specific token. This can be any unique-per-token identifier the partner wishes to provide. One or both of sub or jit are required.

e.g. WP6345789

exp
integer

UNIX timestamp after which the coupon can no longer be used.

nbf
integer

UNIX timestamp before which the coupon can not be used.

Example response(s):
200Generated Coupon
{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJFblkyZWltRFdSIiwiYXVkIjoiSnVsIDIwMjAgQ2FtcGFpZ24iLCJzdWIiOiJjbGllbnRAZXhhbXBsZS5jb20iLCJqdGkiOiJXUDYzNDU3ODkiLCJleHAiOjE1OTQ0MzI5MzIxMjIsIm5iZiI6MTU5MTg0MDk2NTU5NX0.WlWgO9LAsTYCzAkqt-0G3rBYgGlhiHYD61IQNozowH0",
  "url": "http://99designs.com/briefs/partner/create?pc=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJFblkyZWltRFdSIiwiYXVkIjoiSnVsIDIwMjAgQ2FtcGFpZ24iLCJzdWIiOiJjbGllbnRAZXhhbXBsZS5jb20iLCJqdGkiOiJXUDYzNDU3ODkiLCJleHAiOjE1OTQ0MzI5MzIxMjIsIm5iZiI6MTU5MTg0MDk2NTU5NX0.WlWgO9LAsTYCzAkqt-0G3rBYgGlhiHYD61IQNozowH0",
  "couponId": "c4e49b29-6281-4551-97de-984d39a75425"
}
400Bad request
{
  "message": "An error has occurred"
}