> Part of [WHCC Developer Documentation](https://www.whcc.com/developer/llms.txt)

# Creating an Editor

The primary endpoint of the Editor API is creating an editor. Once you've presented your user with some UI to select which [product](https://www.whcc.com/developer/docs/editor-api/products/index.html.md) and [design](https://www.whcc.com/developer/docs/editor-api/designs/index.html.md) they would like to order you can take those pieces of data and create an editor from them. You create an editor by passing in a very simple JSON object, and the response given is a URL to redirect a user to, where they actually do the editing. In most cases this call will happen server side and seamlessly (and transparently) redirect to the editor without someone even knowing they've ended up in a new spot.

> The `userId` property in the payload needs to match the `accountId` (See: [Authentication](https://www.whcc.com/developer/docs/editor-api/authentication/index.html.md) for more information) of the user who will access the editor.

## POST `/editors`

Content-type: application/json

## curl

### CURL Example Request

```shell
curl https://prospector.dragdrop.design/api/v1/editors \
	-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.r3udhowqndkwqneoiqwndjwndei12u390912hrbfhaslkdjbqwiei21nbrhewiuornqwjkfhbaiwodnqwjkbdawuosdhowqubdfjkwbdusandbiwquebio12nedbwbaodpqwnebou12rbwkjalndawuobdnwqndfqwbdfoiwqndpiqwhfiwqnkjdlnwqdnioqwhniorqw3nfjwbaodnwdnqwopd" \
	-H "Accept: application/json" \
	-H "Content-Type: application/json" \
	-d '{"userId":"{{accountId}}","productId":"b7jW7PmsfByoSxQ5m","designId":"ztRMDiHup8ooFhxLr","redirects":{"complete":{"text":"Checkout","url":"https://yourdomain.com/return"},"cancel":{"text":"Change Design","url":"https://yourdomain.com/cancel"}}}'
```

### Example Request Payload

```json
{
	"userId": "{{accountId}}",
	"productId": "b7jW7PmsfByoSxQ5m",
	"designId": "ztRMDiHup8ooFhxLr",
	"redirects": {
		"complete": {
			"text": "Checkout",
			"url": "https://yourdomain.com/return?editor=%EDITOR_ID%"
		},
		"cancel": {
			"text": "Change Design",
			"url": "https://yourdomain.com/cancel"
		}
	},
	"settings": {
		"attributeCategories": [],
		"quantity": {
			"default": 25
		},
		"client": {
			"vendor": "default",
			"accentColor": "#ff0000",
			"studioName": "Sample Studio",
			"hidePricing": true,
			"markupType": "PERCENT",
			"markupAmount": 30
		}
	},
	"photos": [
		{
			"id": "1",
			"name": "Photo IMG_1",
			"url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_1.jpg",
			"printUrl": "https://s3.amazonaws.com/test-bucket-whoa/nonwatermarkedimage.jpg",
			"filetype": "jpg",
			"size": {
				"original": {
					"width": 3600,
					"height": 2401
				}
			}
		},
		{
			"id": "2",
			"name": "Photo IMG_2",
			"url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_2.jpg",
			"filetype": "jpg",
			"size": {
				"original": {
					"width": 2400,
					"height": 3600
				}
			}
		}
	]
}
```

- **`userId`** (string - 255): An internally used ID that's specific to the user you're redirecting into the editor. This value is based on whatever you use to identify who is creating this editor. Your Key combined with your userId is what we used to tie an indvidual user to just their editors. So if you create multiple editor sessions with the same value that user will be able to load all of them simultaneously, but no one else will be able to load those editors, without being passed into them with the appropriate JSON Web Token (JWT).
- **`productId`** (string - 255): The ID of a product that is able to be edited (probably from a designs call).
- **`designId`** (string - 255): The ID of a design that is able to be edited (probably from a designs call).
- **`redirects`** (array): A set of routes that you'd like your user sent to if they leave the editor.
		A key value of **complete** is where a user is sent when they leave the editor via completing their design and choosing to purchase it, this URL is requested containing a payload of what the end outcome of their editor session was.
	A key value of **cancel** is where a user is sent when they click the back or cancel action inside the editor. They are returned without an end output, because they abandoned the design work they did inside the editor.
  - **`url`** (string): The URL you'd like them to be sent to. This URL can contain the placeholder value of `%EDITOR_ID%`, which will be dynamically replaced by the `editorId` for the session.
  - **`text`** (string): The text they should see in the editor UI when completing that action (for example if you're sending them right to Checkout, versus to a Proofing related stage).
- **`settings`** (array, optional): Settings to modify and customize your editor experience.
  - **`quantity`** (string - 255): Items related to the quantity of items that can be ordered.
    - **`default`** (int): Provides the ability to specify the default qty of an editor.
  - **`client`** (string - 255): Options tied to customize the look and functionality of the editor
    - **`vendor`** (string): The visual theme used for display. The string `default` will use the brand-specific accent color created when provisioning your credentials.
    - **`accentColor`** (string): A hex color value used as an accent inside the editor. We dynamically determine buttons and actions based on this color, and attempt to optimize contrast, so even light color values should result in a positive user experience.
    - **`studioName`** (string): Every design our designers have created has a spot for studio branding on the card. This will effect two things in the editor, the ability to dynamical edit that text area, and it will also pre-populate that text box with the string passed in.
    - **`hidePricing`** (bool): If set to true all pricing in the editor will be hidden.
    - **`markupType`** (string): Apply a pricing markup to the prices inside the editor, the only supported value is `PERCENT`.
    - **`markupAmount`** (int - 3): The percentage amount (a positive integer) you'd like to markup, requires also passing `markupType: PERCENT`.
- **`photos`** (object, optional): An object that pre-populates the photo gallery inside the editor with assets provided. Currently JPEG and PNG assets are supported.
  - **`id`** (string - 255): The unique id to refer to this photo.
  - **`name`** (string - 255): The unique name to refer to this photo.
  - **`url`** (string): Publicly accessible file path to get at an image asset to be used in the editor (sometimes watermarked or a smaller version of the image)
  - **`printUrl`** (string): Publicly accessible file path to get the image asset you want to print with (same aspect ratio as url needed)
  - **`filetype`** (string): A value of either "jpg" or "png"
  - **`size`** (array): Pass in the key of "original" to denote the aspect ratio of your file.
    - **`width`** (int): Value in pixels representing the width of the image asset.
    - **`height`** (int): Value in pixels representing the height of the image asset.

### Example Response

```json
{
	"editorId": "2321ej2101293a4e57cdf605",
	"url": "https://www.dragdrop.design/editor/2321ej2101293a4e57cdf605?token=3h2ebaksndohe2o1nen2jkeVCJ9.eyJjbGllbnRLZXlJZCI6InJFMnVlbU1tOGV3ZVFMa243IiwidXNlcklkIjoiMTAwMDEtdGVzdCIsInByb2R1Y3RJZCI6ImI3alc3UG1zZkJ5b1N4UTVtIiwiZGVzaWduSWQiOiJ6dFJNRGlIdXA4b29GaHhMciIsImlzcyI6InBpY2theGUiLC2ebwqhdowqjdnwqjdjkwndw0100218uead0xzUVc5S0ZvR3VaNnR5IiwiZXhwIjoxNTM1MTY2NjM5OTMyfQ.bVnY1DmC9JZYQRklIlCaqusd90109eujnwdnjalXwMtXN4KezaR2-NLpOBIs"
}
```

- **`editorId`** (string - 64): A unique identifier of the editor session.
- **`url`** (string): The path you redirect your user to for them to start editing.

> ## What's Next
>
> Successful [Completion](https://www.whcc.com/developer/docs/editor-api/complete/index.html.md) of the editor redirects a user to the specified `complete` URL.