Ulule API documentation

Do you want to dig into Ulule data or operate crowdfunding campaigns on you own website? This should be a good start.

If you have any question, send us an email at api@ulule.com or open an issue on our github repo.

We will keep you posted shortly with new features and business cases. Enjoy!

Overview

Where possible, Ulule API strives to stick to the REST convention: we use HTTP verbs such as GET, POST, PATCH and DELETE and return appropriate HTTP response codes (2xx for success, 4xx for client errors and 5xx for server errors).

We use JSON to encode all resources and decode all payloads, except file uploads that must be encoded with multipart/form-data.

Pagination

Most endpoints that return a list of resources use the same pagination system. The pagination is cursor-based and returns objects created before a timestamp in reverse chronological order.

Parameters

The limit and since URL query parameters may be used to retrieve different pages.

Parameter Description
limit Maximum number of resources per page, default is 20 and maximum value is 20
since Cursor, must be a timestamp in seconds

Meta object

A meta object is returned in the response beside the actual resource. This object contains field describing the current page and the next page if it exists.

Field Description
limit Current limit value
next Query string of the next page, null if there is no more page

Example

$ curl "https://api.ulule.com/v1/projects/56599/comments?limit=10&since=1522245932"
{
    "comments": [...],
    "meta": {
        "limit": 10,
        "next": "?limit=10&since=1514912554"
    }
}

Languages

The following languages are supported by Ulule API.

Language Code
English en
French fr
Catalan ca
German de
Italian it
Spanish es
Dutch nl
Portuguese pt

I18n

Some payloads and resources contain fields of type i18n object. An i18n object is a JSON object that contains i18n translations. Object keys are language codes (see supported languages), and object values are translation strings.

For example, the description field of the user resource field may look like this:

{
    "en": "This is the description in english",
    "fr": "Ceci est la description en français"
}

In order to get all the translations of an i18n field in the resource, the query string parameter lang=all must be specified in the URL for the three GET, POST and PATCH HTTP methods.

$ curl "https://api.ulule.com/v1/users/105478?lang=all"
{
    "description": {
        "en": "This is a description in english",
        "fr": "Ceci est une description en français",
        "it": "Questo è descritto in italiano",
        "de": "",
        "ca": "",
        "es": ""
    }
}

If the parameter lang is not specified in the URL, the resource returned contains the translation for the parent object lang and the translations present in the request payload.

Let’s take an example project which main language is en, if you update a reward with the following payload:

{
    "description": {
        "fr": "ma superbe description"
    }
}

The returned resource will have the description field in two languages:

  • en because it is the parent resource main language
  • fr because it is provided in the request payload
{
    "description": {
        "en": "my awesome description",
        "fr": "ma superbe description"
    }
}

Versions

Ulule API has a versioning system to manage upgrades without breaking backward-compatibility.

We consider the following changes to be backward-incompatible:

  • Removing a resource field, or changing the type of a resource field.
  • Changing the validation of a parameter, or the permission required to call an endpoint.

When we must introduce a backward-incompatible change, we release a new version named after the current date. To avoid breaking external programs, these versions are always opt-in and must be explicitly requested.

To request a specific version, add the Ulule-Version HTTP header to the request.

Example

$ curl "https://api.ulule.com/v1/projects/56599" -H Ulule-Version:2017-10-10

Versions changelog

2022-10-24

  • This version decreases the permission level required to use the projects.orders_list endpoint. This endpoint is now accessible anonymously. Also, data from anonymous users is now hidden. Project owners may add the ?show_anonymous=true query parameter to show private data from anonymous users.

2022-05-18

  • This version splits the background field of the project resource into two fields background_color and background_image.

2022-05-17

2020-11-10

2020-10-07

  • This version disallows invalid credentials during authentication for endpoints that can be used anonymously. Before this version, if the credentials are invalid and the endpoint can be used anonymously, the request proceeds without being authenticated. With this version, a 401 Unauthorized error is returned.

2020-08-13

  • This version turns the fields_needed field from the project resource into an extra field. It must be explicitly specified.

2020-04-08

2020-03-11

2020-01-27

  • This version changes the format of the date_delivery field from the delivery from YYYY-MM-DD to YYYY-MM.

2019-11-13

  • This version removes the following fields from the project resource, the fields are always present in the delivery embedded resource:
    • address_required
    • phone_number_required
  • This version removes the following fields from the reward resource, the fields are always present in the delivery embedded resource:
    • address_required
    • date_delivery
    • has_shippings
    • phone_number_required
    • shipping_int
    • shipping_nat
    • shippings
  • This version turns the delivery field from the project resource into an extra field. It must be explicitly specified.

2019-11-07

  • This version removes values that do not exist from i18n objects. Before that version, non existing values were always filled with empty strings.

2019-10-28

  • This version removes the following fields from the variant resource, the fields are always present in the parent embedded resource:
    • address_required
    • date_delivery
    • num_products
    • phone_number_required
    • price
    • project_id

2019-09-05

  • This version adds unknown search qualifiers to search terms, whereas they were ignored before that version.

2019-07-24

2019-07-05

  • This version disallows unknown fields in JSON payloads. If an unknown field is present, a UnknownFieldError is returned.

2019-07-03

  • This version makes the username field from the users.create payload optional. If absent, the username is deduced from the local part of the email.

2019-04-11

  • This version turns the account, manager, notes, owner.stats, rewards and user_role fields from the project resource into extra_fields. They must be explicitly specified.

2019-03-07

  • This version adds validation to extra fields: if the request contains an extra field that doesn’t exist, then an error is returned, instead of silently accepting the request without the extra field.

2019-03-06

  • This version turns the main_image, main_tag, owner and user_role fields from the search.projects endpoint into extra_fields. They must be explicitly specified.

2019-02-07

  • This version removes the full_name, name, and region fields from the location resource.

2018-12-12

2018-11-26

  • This version changes the permission of the users.detail endpoint: this endpoint is now accessible to all users.

2018-10-04

  • This version changes the permission of the projects.detail endpoint: this endpoint is now accessible to all users before its status is online.

2018-10-03

2018-09-03

2018-05-22

2018-04-17

  • reward and variant resources
    • date_delivery format is YYYY-MM-DD instead of YYYY-MM-DDTHH:MM:SSZ

2018-04-14

  • proposal resource
    • status_display and type_display are removed
    • status and type are strings

2018-04-11

2017-12-12

  • avatar resource
    • 20 is removed
    • 30 is removed
    • 40 is removed
    • 55 is removed
    • 75 is removed
    • 90 is removed
    • 128 is removed
    • 180 is removed
    • 230 is removed
    • 290 is removed
    • full is removed
  • project.main_image
    • 230x160 is removed
    • 258x145 is removed
    • 260x360 is removed
    • full is removed

2017-10-10

2017-09-19

  • order resource status is a string
  • project resource
    • type is a string
    • currency_display is removed
    • time_left is removed
    • time_left_short is removed
    • image is removed

2017-09-15

Extra fields

Extra fields are a way to control which fields and resources are embedded in a response.

Depending on the use case, API clients sometimes don’t need embedded resources for a specific endpoint, so adding them is a waste of computing resource and network bandwidth. Other clients may want 2 or 3 levels of resource embedding on the same endpoint, so that they can get the data they need with only one request. The goal of extra fields is to address this issue.

To add an extra field to a response, add the extra_fields parameter to the URL.

For example, embed the stats resource into the user resource with the following request:

get /v1/users/:id?extra_fields=stats

To add more than one extra field, separate the values with commas.

For example, embed the analytics, partnerships and sponsorships resources into the project resource with the following request:

get /v1/projects/:id?extra_fields=analytics,partnerships,sponsorships

To nest embedded resource, separate levels of embedding with dots.

For example, embed the orders resource into the user resource, and the project resource into the order resources with the following request:

get /v1/me?extra_fields=orders,orders.project

Errors

Client error resource

Field Type Description
classification string Class of the error
fieldNames array of strings List of the concerned fields
message string Description of the error

The following values are possible for the classification field:

Classification Description
DeserializationError Payload can’t be deserialized because it is malformed
PermissionError User doesn’t have the permission to use this field
RequiredError Field is required
TypeError Field can’t be deserialized because of its type
UnknownFieldError Field is unknown
ValueError Bad value, the message field explains why

Permissions

A permissions field is present in some resources, it specifies the access level on specific fields of the resource for the authenticated user.

{
    "permissions": {
        "self": ["update"],
        "news": ["create"]
    }
}

Authentication

In most cases, data that is publicly readable on the Ulule website is also readable via Ulule API without authentication.

However, to read private data or to write data, requests must be authenticated.

There are three methods to authenticate requests.

  • HTTP Basic
  • API key
  • OAuth2

To read private data, the HTTP Basic and API key methods may be used. To write data, the OAuth2 method is required.

HTTP Basic

$ curl --user "YOUR_USERNAME:YOUR_PASSWORD" "https://api.ulule.com/v1/..."

API Key

The API key of the user can be found in the privacy settings on the Ulule website.

$ curl -H "Authorization: APIKey YOUR_API_KEY" "https://api.ulule.com/v1/..."

OAuth2

This authentication method is only accessible if you have a registered OAuth2 application. Contact api@ulule.com for more information.

Users use their access token for authentication via the Authorization HTTP header.

$ curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://api.ulule.com/v1/..."

Retrieve an access token

To retrieve an access token, use the POST https://api.ulule.com/oauth2/token/ endpoint.

Please, do not forget the slash at the end, just after “token”. This slash is required.

The request must be authenticated with the Basic method with the credentials being your client_id and client_secret.

Payload

Field Description
grant_type Grant type – must be password
password User password
username User username

Example

$ curl -X POST \
    -d "grant_type=password&username=<username>&password=<password>" \
    -u <client_id> \
    https://api.ulule.com/oauth2/token/
{
    "access_token": "PKs6dso48MPRPa4pcKjskjIFwpQMA3",
    "expires_in": 36000,
    "refresh_token": "8Pbypw13OqJDeggvymoUc26djkPZ",
    "scope": "read write",
    "token_type": "Bearer"
}

Or use this Python script:

# access_token.py
import base64
import os

import requests

# Your partner client ID.
CLIENT_ID = os.getenv('CLIENT_ID')

# Your partner client secret.
CLIENT_SECRET = os.getenv('CLIENT_SECRET')

# The user's Ulule username.
USERNAME = os.getenv('USERNAME')

# The user's Ulule password.
PASSWORD = os.getenv('PASSWORD')

# We need to encode the client ID and client secret in base64 before
# passing it as a header.
def get_basic_auth_header(user, password):
    user_pass = '{0}:{1}'.format(user, password)
    auth_string = base64.b64encode(user_pass.encode('utf-8'))
    auth_headers = {'AUTHORIZATION': 'Basic ' + auth_string.decode("utf-8")}
    return auth_headers

# Execute the POST request with: grant_type, username and password as
# POST parameters. Do not forget to add HTTP Basic header.
response = requests.post(
    'https://api.ulule.com/oauth2/token/',
    data={
        'grant_type': 'password',
        'username': USERNAME,
        'password': PASSWORD,
    },
    headers=get_basic_auth_header(CLIENT_ID, CLIENT_SECRET))

# Our response.
data = response.json()

# Expect a 200 status code.
assert response.status_code == 200

print('Access-Token: %s' % data.get('access_token'))
print('Refresh-Token: %s' % data.get('refresh_token'))

This script can be easily rewritten in any programing langage.

You can run this script by installing the requests package and passing variables as environment variables:

$ pip install requests
$ CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret USERNAME=user-username PASSWORD=user-password python access_token.py
Access-Token: user-access-token
Refresh-Token: user-refresh-token

You now have an access token to authenticate the user.

Refresh the access token

Access tokens expire after 10 hours.

Because you don’t store user passwords in plain text in your database, you can’t generate new access tokens automatically without asking the user credentials again. In terms of user experience, this would be pretty bad.

To address this issue, we also provide a refresh token which allows you to generate a new access token:

# refresh_token.py
import base64
import os

import requests

# Your partner client ID.
CLIENT_ID = os.getenv('CLIENT_ID')

# Your partner client secret.
CLIENT_SECRET = os.getenv('CLIENT_SECRET')

# The user's refresh token.
REFRESH_TOKEN = os.getenv('REFRESH_TOKEN')

# We need to encode the client ID and client secret in base64 before
# passing it as a header.
def get_basic_auth_header(user, password):
    user_pass = '{0}:{1}'.format(user, password)
    auth_string = base64.b64encode(user_pass.encode('utf-8'))
    auth_headers = {'AUTHORIZATION': 'Basic ' + auth_string.decode("utf-8")}
    return auth_headers

# Execute the POST request with: grant_type and refresh_token
# POST parameters. Do not forget to add HTTP Basic header.
response = requests.post(
    'https://api.ulule.com/oauth2/token/',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': REFRESH_TOKEN,
    },
    headers=get_basic_auth_header(CLIENT_ID, CLIENT_SECRET))

# Our response.
data = response.json()

# Expect a 200 status code.
assert response.status_code == 200

print('Access-Token: %s' % data.get('access_token'))

You can run this script by installing the requests package and passing variables as environment variables:

$ pip install requests
$ CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret REFRESH_TOKEN=user-refresh-token python refresh_token.py
Access-Token: user-access-token

You now have a new access token to re-authenticate the user.

Ulule Connect

Ulule connect allows users to connect their Ulule account to partner websites.

The workflow is:

  1. User is on partner website
  2. Partner needs to access user data
  3. User clicks on “Sign In” button on partner website
  4. This button redirects to Ulule connect URL
  5. If the user does not have an existing Ulule account, the interface offers to create a new one
  6. If the user already has an account, he or she can sign in with his or her Ulule credentials
  7. At the end of sign in / sign up process, user is redirected to the redirect_uri
  8. The user access token is returned to the redirect_uri

Authorize user with Ulule Connect

The Ulule Connect URL is https://ulule.com/oauth2/authorize/.

The following query parameters are required.

Field Description
client_id Partner client ID
redirect_uri Registered partner redirect URI
response_type OAuth2 response type – must be token or code

A convenient way is to use this URL in a pop-up.

form.jpg authorize.jpg

The redirect URI, or redirection endpoint, is used to redirect users after sign in or sign up. Only registered redirect URIs are allowed. Only one registered URI can be set in the Ulule Connect request, but you can register as many as you want.

If response_type is token, the access token is accessible at the redirect URI as a URL fragment. You can stop reading.

If response_type is code, an access code is sent to the redirect URI via the code URL query parameters and the access token can be obtained from it. Read the next section.

Retrieve user access token from authorization code

Use the POST https://api.ulule.com/oauth2/token/ endpoint as described in the OAuth2 section.

Payload

Field Description
code Authorization code retrieved from the code URL query parameter at redirect_uri
grant_type Grant type – must be authorization_code
redirect_uri Redirected URI used to obtain the code

Example

Take a look at this Python script:

# access_token_from_code.py
import base64
import os

import requests

# Your partner client ID.
CLIENT_ID = os.getenv('CLIENT_ID')

# Your partner client secret.
CLIENT_SECRET = os.getenv('CLIENT_SECRET')

# The grant code.
GRANT_CODE = os.getenv('GRANT_CODE')

# Your registered redirect URI.
REDIRECT_URI = os.getenv('REDIRECT_URI')

# We need to encode in base64 the client_id and client_secret before
# passing it as a header.
def get_basic_auth_header(user, password):
    user_pass = '{0}:{1}'.format(user, password)
    auth_string = base64.b64encode(user_pass.encode('utf-8'))
    auth_headers = {'AUTHORIZATION': 'Basic ' + auth_string.decode("utf-8")}
    return auth_headers

# Execute the POST request with: grant_type, code and redirect_uri as
# POST parameters. Do not forget to add HTTP Basic header.
response = requests.post(
    'https://api.ulule.com/oauth2/token/',
    data={
        'grant_type': 'authorization_code',
        'code': GRANT_CODE,
        'redirect_uri': REDIRECT_URI,
    },
    headers=get_basic_auth_header(CLIENT_ID, CLIENT_SECRET))

# Our response.
data = response.json()

# Expect a 200 status code.
assert response.status_code == 200

print('Access-Token: %s' % data.get('access_token'))
print('Refresh-Token: %s' % data.get('refresh_token'))

You can run this script by installing the requests package and passing variables as environment variables:

$ pip install requests
$ CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret GRANT_CODE=your-grant-code REDIRECT_URI=your-redirect-uri python access_token_from_code.py
Access-Token: user-access-token
Refresh-Token: user-refresh-token

Guest users

It’s possible to authenticate a user with just an email, and without creating a user account. Guest users have limited access to Ulule API, which is defined and documented per endpoint.

Create a guest user

To create a guest user and retrieve an access token, the workflow is similar to the OAuth2 method. Use the POST https://api.ulule.com/oauth2/token/ endpoint with the guest_email grant type.

Payload

Field Description
email User email
grant_type Grant type – must be guest_email

Reference

This is the reference of all Ulule API resources.

User

The user resource represents a user registered on the Ulule website, possibly via a partner website.

User resource

Field Type Description
absolute_url string Link to the profile page of the user on the Ulule website
avatar avatar resource Avatar of the user
birthday string Birthday of the user, with format YYYY-MM-DD – only accessible to oneself
country string Two-letter ISO code of the country where the user lives.
date_joined string Date at which the user created an account, with RFC 3339 format
description i18n object Short description of the user
email string Email of the user – only accessible to oneself
first_name string First name of the user
has_avatar bool True if user has an avatar. Otherwise a default avatar is assigned to the user
id int Unique ID of the user
is_completed bool Deprecated since the 2018-05-22 version change. Must be true for a user to create an order. The following fields must be filled for is_completed to be true: birthday, country, email, nationality, first_name, last_name
is_staff bool True if user is staff
lang string Language of the user
last_login string Date at which the user last logged in, with RFC 3339 format
last_name string Last name of the user
location string Location of the user
name string Concatenation of first name and last name if they exist, username otherwise
nationality string Two-letter ISO code of the nationality of the user – only accessible to oneself
personal_id_number string Personal ID number – only accessible to oneself
presentation i18n object Longer presentation of the user
resource_uri string URL of the user resource
screenname string
timezone string Timezone of the user
username string Username

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
channels array of channel resources Channels owned by the user
contact_lang string Preferred language for contacting the user – only accessible to staff
latest_project_comment comment resource Latest comment of the user for the project with the given ID – only accessible on the project supporter list endpoint
latest_project_order order resource Latest order of the user for the project with the given ID – only accessible on the project supporter list endpoint
newsletters array of strings Slugs of the newsletters the user is subscribed to

Retrieve authenticated user

Retrieves the authenticated user.

get /v1/me

Retrieve a user

Retrieves the user with the given ID.

get /v1/users/:id
Parameter Description
:id User ID

Create a user

Creates a new user. The created user is a member of the partner with the given slug. This endpoint is only accessible to partner users.

post /v1/partners/:slug/users
Parameter Description
:slug Partner slug

Payload

Field Type Description
dry_run bool If true, fields are checked but the user is not created – optional
email string Email of the user – required, max 254 characters
ip_address string IP address of the user – optional
lang string Language of the user – optional
password1 string Password of the user – required, max 128 characters, must have a score of at least 1 with the zxcvbn password strength estimator
username string Username – optional, max 80 characters

Update a user

Updates the user with the given ID. This endpoint is only accessible to oneself.

patch /v1/users/:id
Parameter Description
:id User ID

Payload

Field Type Description
birthday string Birthday of the user – must have YYYY-MM-DD format and year must be greater than 1901
country string Country where the user lives – must be two-letter ISO code
contact_lang string Preferred language for contacting the user – must be one of the supported languages, only accessible to staff
description i18n object Short description of the user
email string Email of the user
first_name string First name of the user – max 30 characters
ip_address string IP address of the user – must be ipv4 or ipv6
last_name string Last name of the user – max 30 characters
lang string Language of the user – must be one of the supported languages
location string Location of the user – max 255 characters
nationality string Nationality of the user – must be two-letter ISO code
newsletters array of strings Slugs of the newsletters the user is subscribed to
presentation i18n object Longer presentation of the user
screenname string Screenname of the user – max 30 characters
username string Username – max 80 characters

Delete a user

Deletes the user with the given ID. This endpoint is only accessible to oneself.

delete /v1/users/:id
Parameter Description
:id User ID

List all partner members

Retrieves all the users that has been registered via the partner with the given slug. This endpoint is only accessible to partner users.

The response is paginated.

get /v1/partners/:slug/users
Parameter Description
:slug Partner slug

List all project supporters

Retrieves all the users that are supporters of the project with the given ID. If the project is online, this endpoint doesn’t require authentication. Otherwise, it is only accessible to the project owner.

The response is paginated.

get /v1/projects/:id/supporters
Parameter Description
:id Project ID

Create a discussion thread with a user

Creates a discussion thread between the authenticated user and the user with the given ID. One of the following condition must be fulfilled for a user to have the permission to reach another one:

  • One of the users is staff
  • One of the users is a partner member and the other one if a partner moderator
  • One of the users is a project supporter and the other one is the project owner
  • One of the users is a project supporter and the other one is a project editor
post /v1/users/:id/threads
Parameter Description
:id User ID

Payload

Field Type Description
message string Body of the first message in the thread
subject string Subject of the thread – required, must be between 3 and 255 characters

Ban user

Ban the user with the given id. This endpoint is only accessible to staff.

post /v1/users/:id/ban
Parameter Description
:id User ID

Offboard team member

Offboard the user with the given id. This endpoint is only accessible to staff.

post /v1/users/:id/offboard
Parameter Description
:id User ID

Payload

Field Type Description
user_id int User ID used to substitute the offboarded user – optional

List all official users

Retrieves all the official users.

The response is paginated.

get /v1/officialusers

Query parameters

Parameter Type Description
country string Country of the official user
lang string Lang of the official user

Avatar

The avatar resource represents the avatar belonging to a user. A user can only have one avatar.

Avatar resource

Field Type Description
id int Unique ID of the avatar
name string Name of the uploaded image file
value string Path to the file
versions object Object whose keys are strings representing the image dimensions (20x20, 30x30, 40x40, 55x55, 75x75, 90x90, 128x128, 180x180, 230x230, 290x290, and full for the image in its original size), and whose values are image version objects defined below

Image version object

Field Type Description
height int Image height in pixel, null in case it is the original version of the file
url string Image URL
width int Image width in pixel, null in case it is the original version of the file

Create a user avatar

Creates a new avatar for the user with the given ID. This endpoint returns an error if the user already has an avatar. This endpoint is only accessible to oneself.

post /v1/users/:id/avatars
Parameter Description
:id User ID

Payload

The Content-Type must be multipart/form-data.

Field Type Description
image file Image file – required, format must be GIF, JPEG or PNG, size must be less than 5MB

Update an avatar

Updates the avatar with the given ID. This endpoint is only accessible to the owner of the avatar.

patch /v1/avatars/:id
Parameter Description
:id Avatar ID

Payload

The Content-Type must be multipart/form-data.

Field Type Description
image file Image file – format must be GIF, JPEG or PNG, size must be less than 5MB

Delete an avatar

Deletes the avatar with the given ID. This endpoint is only accessible to the owner of the avatar.

delete /v1/avatars/:id
Parameter Description
:id Avatar ID

Link

Users may add social websites links to their profile. Links may also be attached to proposals.

Field Type Description
crawlable bool Whether link is crawlable
followers_count int Number of followers
id int Unique ID of the link
url string URL of the link
views_count int Number of views

Creates a new link. This endpoint is anonymously accessible.

post /v1/links

Payload

Field Type Description
url string URL of the link – required, max 200 characters

Notification

By default, users receive notifications when certain events happen.

The list of those notifications can be read via the list user notifications endpoint, and updated via the update user notifications endpoint.

By default, users also receive notifications when a news is published in one of the projects they are fan of. Those notifications can be read via the list user projects endpoint, and updated via the update project notifications endpoint.

User notification resource

Field Type Description
cancelled_support bool I received a cancellation of a support on my projects
follow bool I’m followed by someone new
join bool Someone from my connections joined Ulule
new_badge_following bool Someone I’m following received a new badge
new_badge bool I received a new badge
new_comment_on_project_news bool I received a new comment on one of my posted news
new_comment_on_project bool I received a new comment on my projects
new_faq bool I received a new question on one of my projects
new_support bool I received a new support on my projects
receive_message bool Someone sent me a private message
support bool Someone from my connections has supported a new project

List user notifications

Retrieves all the notifications for the user with the given ID. This endpoint is only accessible to oneself.

get /v1/users/:id/notifications
Parameter Description
:id User ID

Update user notifications

Updates the notifications for the user with the given ID. This endpoint is only accessible to oneself.

patch /v1/users/:id/notifications
Parameter Description
:id User ID

Payload

Field Type
cancelled_support bool
follow bool
join bool
new_badge_following bool
new_badge bool
new_comment_on_project_news bool
new_comment_on_project bool
new_faq bool
new_support bool
receive_message bool
support bool

Update project notifications

Updates the authenticated user notifications for the project with the given ID.

patch /v1/projects/:id/notifications
Parameter Description
:id Project ID

Payload

Field Type
news bool

Newsletter

Newsletter resource

Field Type Description
is_subscribed bool Whether the authenticated user is subscribed to the newsletter
name i18n object Name of the newsletter
slug string Unique slug of the newsletter

List newsletters

get /v1/newsletters

Subscribe contact to newsletter

Subscribe an email to a given newsletter. The email must not belong to an existing user.

post /v1/newsletters/:slug
Parameter Description
:slug Newsletter Slug

Payload

Field Type Description
email string Email

Project

The project resource represents a project hosted on Ulule.

There are two types of project on Ulule and they have different objectives: projects of type project are for collecting a certain amount of money, and projects of type presale are for receiving a certain number of pre-orders.

The project status can have the following values:

Status Description
new The project has been created from a validated proposal
pending The project owner has submitted the project to validation
pending-owner The moderation team is waiting for a change or an answer from the project owner
pending-final-validation The moderation team has sent the project to final validation
validated The moderation team has validated the project
online The project owner has published the project
refused The moderation team has refused the project
waiting The moderation team has put the project to a waiting state

Project resource

Field Type Description
absolute_url string Link to the project page on the Ulule website
amount_raised int Amount raised in project currency
analytics_count int
background_color i18n object Background color of the project
background_image i18n object where values are image resources Background image of the project
comments_count int
committed int
country string Two-letter ISO code of the country
currency string Three-letter ISO code of the currency
date_end string Date at which the funding campaign ends, with RFC 3339 format
date_end_extra_time string Date at which the funding campaign extra time ends, with RFC 3339 format
date_start string Date at which the funding campaign starts, with RFC 3339 format
description i18n object Main description of the project
description_funding i18n object Description of what are funds for
description_yourself i18n object Description of the owner of the project
discussions_thread_id int
fans_count int Number of fans
finished bool True if the funding campaign is finished
goal_raised bool True if the current sum collected is superior to the project goal
goal int Goal in the project currency if type is project, or number of pre-orders if type is presale
id int Unique ID of the project
is_cancelled bool True if the project is cancelled
is_online bool True if the project is online
lang string Main language of the project
location location resource Location of the project
lowest_contribution_amount int Lowest contribution possible in the project currency
main_image i18n object where values are image resources Main image of the project
main_tag tag resource Main tag of the project
name i18n object Name of the project
nb_days int Duration of the funding campaign in days
nb_products_sold int The number of orders for project of type presale
news_count int Count of news published
owner user resource Owner of the project
payment_methods array of strings Payment methods supported by the project – any number of the available payment methods
percent int Percentage of the goal raised on the goal targeted
resource_uri string URL of the project resource
slug string Unique slug of the project
sponsorships_count int
status string Status of the project (online, new, pending, pending-owner, validated, refused, waiting, pending-final-validation)
subtitle i18n object Subtitle of the project
supporters_count int Number of supporters
timezone string Timezone of the project
type string Type of the project (presale or project)
urls urls resource URLs of the project
video i18n object where values are video resource Video of the project
visible bool

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
account account resource Project account – only accessible to the project owner
analytics array of analytics tags Project analytics tags
billing billing resource Project billing – only accessible to the project owner
default_manager user resource A default manager for the project, based on its default partnership – only accessible to the project owner
delivery delivery resource Delivery settings for the project
fields_needed array of strings List of fields that must be filled by the project owner before the project can be submitted for validation to the moderation team – only accessible to the project owner
latest_news news resource Latest news
latest_supporter user resource Latest supporter
links array of links Links attached to the project, this extra field also adds the post_campaign_link link resource field
manager user resource Project manager – only accessible to the project owner
notes notes resource Project notes – only accessible to staff
owner.contact_lang string Preferred language for contacting the project owner – only accessible to staff
owner.stats user stats resource Stats of the project owner – only accessible to staff
partnerships array of partnerships Partnerships of the project
proposal proposal resource Proposal from which the project was created – only accessible to the project owner
proposal.links array of links Links attached to the proposal from which the project was created – only accessible to staff
proposal.validator user resource User who validated the proposal from which the project was created – only accessible to staff
rewards array of rewards Project rewards
slugs array of slugs Slugs of the project – only accessible to staff
sponsorships array of sponsorships Sponsorships of the project
tags array of tags Tags of the project
user_orders array of orders Orders the authenticated user has completed on project
user_role string Relation between the project and the authenticated user, can be null, fan, supporter and owner

The field permissions is present in the following endpoints:

Fields Possible values
self update
news create

Payment methods

The following payment methods are supported:

Payment method
bankwire
check
creditcard
directdebit
ideal
maestro
paylib
paypal
saving

Billing resource

Field Type Description
invoice invoice resource Project invoice
payment_status string Project payment status, can be one of waiting, processing, ready, error, payment-processing, completed

Invoice resource

Field Type Description
url string Invoice URL

Location resource

Field Type Description
city string City
country string Two-letter ISO code of the country

Note resource

Field Type Description
billing string Note about billing
manager string Note about management

Retrieve a project

Retrieves the project with the given ID.

get /v1/projects/:id
Parameter Description
:id Project ID

Update a project

Updates the project with the given ID. This endpoint is only accessible to the project owner.

patch /v1/projects/:id
Parameter Description
:id Project ID

Payload

Field Type Description
background_image_id project image payload Background image
description i18n object Main description of the project
description_funding i18n object Description of what the funds are for
description_yourself i18n object Description of the owner of the project
main_image_id project image payload Main image
name i18n object Name of the project
post_campaign_link link payload Post-campaign link
slug string Slug of the project – must be unique, max 250 characters
subtitle i18n object Subtitle of the project
tags array of ints ID of tags related to the project
timezone string Timezone of the project
video_url i18n object URLs of the video of the project

Also, it’s possible to create, update, and delete links with the following payload fields.

Field Type Description
create_links array of create-project-link payloads Create links
update_links array of update-project-link payloads Update links – the link id field must be set
delete_links array of ints Delete links – the ints in the array must be existing links id fields

In addition, the following fields can’t be updated after the project has been validated by the moderation team, they can only be updated when the project status is one of new, pending and pending-owner.

Field Type Description
account_id int ID of the project owner account
country string Two-letter ISO code of the country
currency string Three-letter ISO code of the currency
date_end string Date at which the funding campaign ends, with RFC 3339 format
goal int Goal of the project
lang string Main language of the project
main_tag_id int ID of the main tag of the project
nb_days string Duration of the funding campaign in days
type string Project type – must be project or presale

Finally, the following fields can’t be updated by the project owner, they can only be updated by staff users.

Field Type Description
answer_code string Answer code – must be one of accepted, need-moderation, sent-to-okpal, refused
channel_ids array of ints IDs of channels related to the project and ordered by position
comments_enabled string Enable comments – must be one of everyone, supporters, disabled
discussion_disabled bool Disable discussion
manager_id int64 Manager ID
manager_type string Manager type – must be one of specialist, success
notes notes resource Notes
owner_id int64 Owner ID
quality_score string Quality score – must be one of A, B, C, X
recommendable bool Allow to show this project to other project owners for inspiration
status string Project status
supporters_disabled bool Don’t show supporters
unread bool Show this project in moderation team pipe
visible bool Index this project in search engines

Project image payload

The project image payload is a JSON object where keys are language codes (see supported languages) and values are ids of image resources. The image must belong to the project and the image type must match the field: it must be main or main-draft if the field is main_image_id, and it must be background or background-draft if the field is background_image_id.

Field Type Description
title i18n object Title
url string URL – required, must be a valid url
Field Type Description
title i18n object Title
url string URL – must be a valid url

Submit a project

Submits the project for review to the moderation team. This endpoint is only accessible to the project owner. The project owner can send a message to the moderation team. This message will be added to the project discussion thread.

The project status must not be pending, and the following fields must be set (i18n fields must be set in the project default language):

  • country
  • currency
  • description
  • goal (if type is project)
  • main_image
  • name
  • nb_product_min (if type is presale)
  • owner.avatar
  • owner.email
  • owner.location
  • rewards
  • slug
  • subtitle
  • timezone
  • one of date_end anf nb_days
  • account.is_completed must be true
post /v1/projects/:id/submit
Parameter Description
:id Project ID

Payload

Field Type Description
message string Message to the moderation team – optional

Publish a project

Publishes the project and make it publicly visible. This endpoint is only accessible to the project owner.

The project status must be validated.

The project owner may update the date_end and timezone fields. The date_end field can’t be updated to a date that is more than 5 days before or after the original date_end or current day plus nb_days: old date_end - 5 < new date_end < old date_end + 5 where old date_end is the previous date_end or current date + nb_days if date_end is null.

The date_end field must be set for a project to go online.

post /v1/projects/:id/publish
Parameter Description
:id Project ID

Payload

Field Type Description
date_end string Date at which the funding campaign ends, with RFC 3339 format – optional
timezone string Timezone of the project – optional

Unpublish a project

Unpublished the project. This endpoint is only accessible to staff.

This endpoint is typically used when the project owner mistakenly published the project too soon.

post /v1/projects/:id/unpublish
Parameter Description
:id Project ID

Moderate a project

Moderate the project. This endpoint is only accessible to staff.

This endpoint is used for the project moderation.

post /v1/projects/:id/moderate
Parameter Description
:id Project ID

Payload

Field Type Description
answer_code string Reference code for the moderation
answer_html string Message in HTML used as response in the project discussion
status string Project status

List partner projects

Retrieves all the projects that have a partnership with the partner with the given slug. This endpoint is only accessible to partner users, unless the status=online query parameter is present.

The response is paginated.

get /v1/partners/:slug/projects
Parameter Description
:slug Partner slug

Query parameters

The list can be filtered with the following query parameters:

Parameter Description
is_winner Whether the project is a prizewinner. Can be true or false
status Project status. Can be one of online, new, pending, pending-owner, validated, refused, waiting, pending-final-validation

List sponsor projects

Retrieves all the projects sponsored by the sponsor with the given user ID.

The response is paginated.

get /v1/sponsors/:user_id/projects
Parameter Description
:user_id Sponsor user ID

List user projects

Retrieves all the projects related to the user with the given ID.

The response is paginated.

get /v1/users/:id/projects
Parameter Description
:id User ID

Query parameters

Parameter Description
sort Sort the project list. Can be one of created_at, supported_at, followed_at. Default is created_at.
state Kind of relationship between the user and the projects. Can be one of online, supported, followed, created. created is only accessible to oneself.

Project discussion

Projects have one discussion thread where the project owner and the moderation team can talk to each other. The two following endpoints allow staff users that are not in the recipient list to read and join the project discussion thread.

Read messages from project discussion thread

GET /v1/projects/:id/messages where :id is the project ID.

Join a project discussion thread

POST /v1/projects/:id/join-thread where :id is the project ID.

Project likes

Users can like projects to receive notifications. Project owners and backers automatically like a project, and cannot unlike it.

Like a project

POST /v1/projects/:id/like where :id is the project ID. This endpoint is accessible to guest users.

Unlike a project

POST /v1/projects/:id/unlike where :id is the project ID. This endpoint is accessible to guest users.

Category and Tag

There are two kinds of tag. The main ones are categories and can be used as a project main tag. The secondary ones are subtags, they always belong to a category and can be used as project tags.

Tag resource

Field Type Description
absolute_url string Link to the category page on the Ulule website
category Tag resource Parent category, only present in the list-tags endpoint
id int Unique ID of the tag
name i18n object Name of the tag
position int Position of the tag
slug string Unique slug of the tag

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
featured_project project resource Featured project

Retrieve a category

Retrieves the category with the given slug.

get /v1/categories/:slug
Parameter Description
:slug Category slug

List categories

Retrieves all categories.

get /v1/categories

List tags

Retrieves all tags (categories and subtags).

get /v1/tags

List category subtags

Retrieves all the subtags that belong to the category with the given ID.

get /v1/categories/:id/tags
Parameter Description
:id Category ID

List project tags

Retrieves all the tags of the project with the given ID. This endpoint is only accessible if the project status is online, or if the authenticated user is the project owner.

get /v1/projects/:id/tags
Parameter Description
:id Project ID

Image

There are four different kinds of images:

Type Description
main The main image of a project. It is the main image displayed on the project page. It is also used to preview the project in a list of projects. A project can have only one main image per language
background The background image of a project. It is only displayed on the project page. It can consist of a background color and/or an image file. A project can have only one background image per language
secondary Secondary images are image files uploaded to Ulule, which can be embedded into HTML fields such as project.description
reward Reward images are image files uploaded to Ulule, which can be set to a reward via the projects.create_reward and the rewards.update endpoints.

In addition, there are two more types that are useful to update the project main images and background images atomically via the projects.update endpoint. The values are main-draft and background-draft.

Image resource

Field Type Description
color string HTML hex color code. This field is only present for images of type background that have a color
id int Unique ID of the image
lang string Language of the image
name string Filename. This field is not present for images of type background without an image file
type string Type of the image
url string Publicly available URL of the image. This field is only present for images of type background that have a URL
value string Path to the file. This field is not present for images of type background without an image file
versions object Object whose keys are strings representing the image dimensions (small, medium, large, and full for the image in its original size), and whose values are image version objects. This field is not present for images of type background

Create a project image

Creates an image. This endpoint is only accessible to the project owner.

post /v1/projects/:id/images
Parameter Description
:id Project ID

Payload

The Content-Type must be multipart/form-data.

Field Type Description
image file Image file – required for all types excepted background and background-draft, format must be GIF, JPEG or PNG, size must be less than 5MB. Images of type main and main-draft must be at least 640x360. Images of type background and background-draft must be at least 1440x530.
lang string Image language – required
type string Image type – required

List project images

Retrieves all images that belong to the project with the given ID.

The response is paginated.

get /v1/projects/:id/images
Parameter Description
:id Project ID

Video

A project can have one video per language. The video will be displayed on the project page.

Video resource

Field Type Description
id int Unique ID of the video
language string Language of the video
url string URL of the video

The video resource also contains the following oEmbed fields.

Field Type
author_name string
author_url string
height int
html string
provider_name string
provider_url string
thumbnail_height int
thumbnail_width int
title string
type string
version string
width int

Reward

Reward resource

Field Type Description
available bool Whether the reward is available
delivery delivery resource Delivery settings for the reward, copied from project delivery settings, or custom for the reward
description i18n object Description of the reward, can contain HTML tags
has_custom_delivery bool Whether the reward has custom delivery settings
id int Unique ID of the reward
image i18n object where values are image resources Image of the reward
is_featured bool Whether the reward is featured
is_hidden bool Whether the reward is hidden
num_products int Number of products that are counted when the reward is ordered, only valid if project is in presale mode
position int Position of the reward
price int Price of the reward
project_id int Unique ID of the related project
resource_uri string URL of the reward resource
stock int Maximum number of rewards the project owner can produce. If null there is no limit
stock_available int Count of remaining rewards, null if stock is null, otherwise equal to stock - stock_taken
stock_taken int Count of taken reward items
title i18n object Title of the reward
variants array of variant resources Variants of the reward

Variant resource

Field Type Description
available bool Whether the variant is available
description i18n object Description of the variant, can contain HTML tags
id int Unique ID of the variant
parent reward resource Parent of the variant
stock int Maximum number of variants the project owner can produce. If null there is no limit
stock_available int Count of remaining variants, null if stock is null, otherwise equal to stock - stock_taken
stock_taken int Count of taken variant items

Retrieve a reward

Retrieves the reward with the given ID. This endpoint is only accessible if the related project status is online, or if the authenticated user is the project owner.

get /v1/rewards/:id
Parameter Description
:id Reward ID

Create a project reward

Creates a new reward for the project with the given ID. This endpoint is only accessible to the project owner.

post /v1/projects/:id/rewards
Parameter Description
:id Project ID

Payload

Field Type Description
description i18n object Description – optional
dry_run bool Validate the payload, but do not actually create the reward
image_id reward image payload Image – optional
is_featured bool Whether the reward is featured. There can be only one featured reward per project – optional, default is false
is_hidden bool Whether the reward is hidden – optional, default is false
num_products int Number of products that are counted when the reward is ordered – optional, only valid if project is in presale mode
price float Price – required, must be between 0 and 1e10, must be an int if project is in project mode
stock int Stock – optional
title i18n object Title – required in project lang, max 200 characters
variants array of create-variant payloads Variants – optional

Reward image payload

The reward image payload is a JSON object where keys are language codes (see supported languages) and values are ids of image resources. The image must be in the same project as the reward and the image type must be reward.

Create variant payload

Field Type Description
description i18n object Description – required in project lang, max 200 characters
position int Position – required, must be greater than 0
stock int Stock – optional

Update a reward

Updates the reward with the given ID. This endpoint is only accessible to the project owner.

patch /v1/rewards/:id
Parameter Description
:id Reward ID

Payload

Field Type Description
description i18n object Description
dry_run bool Validate the payload, but do not actually update the reward
image_id reward image payload Image
is_featured bool Whether the reward is featured. There can be only one featured reward per project.
is_hidden bool Whether the reward is hidden
num_products int Number of products that are counted when the reward is ordered – optional, only valid if project is in presale mode
price float Price, must be between 0 and 1e10
stock int Stock
title i18n object Title – max 200 characters

Also, it’s possible to create, update, and delete variants with the following payload fields.

Field Type Description
create_variants array of create-variant payloads Create variants
update_variants array of update-variant payloads Update variants – the variant id field must be set
delete_variants array of ints Delete variants – the ints in the array must be existing variants id fields

Update variant payload

Field Type Description
description i18n object Description – max 200 characters
position int Position – must be greater than 0
stock int Stock

It is possible to reset the delivery settings of the reward with the following payload field:

Field Type Description
delete_custom_delivery bool If true, delete the reward custom delivery settings. The has_custom_delivery field is set to false, and the delivery embedded resource is set to the project delivery

Delete a reward

Deletes the reward with the given ID. This endpoint is only accessible to the project owner.

delete /v1/rewards/:id
Parameter Description
:id Reward ID

List project rewards

Retrieves all the rewards that belong to the project with the given ID. This endpoint is only accessible if the project status is online, or if the authenticated user is the project owner.

The response is paginated.

get /v1/projects/:id/rewards

Parameter Description
:id Project ID

Delivery

Deliveries are options related to reward shippings, pick up points, and fields that may be required from backers during the checkout step. Projects have default delivery options, and rewards inherit delivery options from their parent project. Rewards may then override delivery options.

Note that pick up points may not be overriden, they are always defined for every rewards of a project, never for an individual reward.

Delivery resource

Field Type Description
address_required bool Whether backers must specify a shipping address when ordering a reward
date_delivery string Estimated date of delivery of rewards, with the YYYY-MM format
force_address_required bool Whether an address is required for orders without rewards, only present in the project delivery resource
has_shippings bool Whether there are shipping costs
phone_number_required bool Whether backers must specify the phone number in the shipping address when ordering a reward
pickup_points array of pickup point resources Pick up points, only present in the project delivery resource
shipping_int int International shipping cost
shipping_nat int National shipping cost
shipping_type string Shipping type – can be one of none, national-only, national-and-some-countries, worldwide
shippings array of shipping resource Per country shippings

Shipping resource

Field Type Description
amount float Shipping cost
countries array of strings Array of countries, represented by their two-letter ISO code. If zone is not empty, countries is automatically filled with countries from zone
id int Unique ID of the shipping
zone string Shipping zone

Shipping zones

The following shipping zones are supported.

Zone Country codes
overseas-fr BL, GF, GP, MF, MQ, NC, PF, PM, RE, WF, YT
european-union AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK
europe european-union + AD, AL, AM, BA, BY, CH, IS, KZ, LI, MC, MD, ME, MK, NO, RS, SM, UA, VA

Pickup point resource

Field Type Description
address address resource Address
description i18n object Description
id int Unique ID of the pickup point
name i18n object Name
raw_address i18n object Raw address

Update project or reward delivery settings

Updates the delivery settings of the project or the reward with the given ID. This endpoint is only accessible to the project owner.

patch /v1/projects/:id/delivery
patch /v1/rewards/:id/delivery

Parameter Description
:id Project ID

Payload

Field Type Description
address_required bool Whether backers must specify a shipping address when ordering a reward
date_delivery string Date at which the delivery is expected, with the YYYY-MM format – required
force_address_required bool Whether an address is required for orders without rewards, only valid in the project delivery payload
phone_number_required bool Whether backers must specify the phone number in the shipping address when ordering a reward
shipping_int int International shipping cost
shipping_nat int National shipping cost
shipping_type string Shipping type – required, must be one of none, national-only, national-and-some-countries, worldwide

Also, it’s possible to create, update, and delete shippings with the following payload fields.

Field Type Description
create_shippings array of create-shipping payloads Create shippings
update_shippings array of update-shipping payloads Update shippings – the shipping id field must be set
delete_shippings array of ints Delete shippings – the ints in the array must be existing shippings id fields

Similarly, project pickup points may be created, updated, and deleted with the following payload fields:

Field Type Description
create_pickup_points array of create-pickup-point payloads Create pickup points
update_pickup_points array of update-pickup_point payloads Update pickup points – the pickup point id field must be set
delete_pickup_points array of ints Delete pickup points – the ints in the array must be existing pickup point id fields

Create shipping payload

Field Type Description
amount float Shipping cost – required, must be between 1 and 999.99
countries array of strings Countries, represented by their two-letter ISO code – one of countries and zone must be set
zone string Shipping zone – one of countries and zone must be set

Update shipping payload

Field Type Description
amount float Shipping cost – can be between 1 and 999.99
countries array of strings Countries, represented by their two-letter ISO code
zone string Shipping zone

Create pickup point payload

Field Type Description
address address payload Address
description i18n object Description – max 200 characters
name i18n object Name – required, max 100 characters
position int Position – required, must be greater than 0
raw_address i18n object Raw address – max 200 characters

Update pickup point payload

Field Type Description
address address payload Address
description i18n object Description – max 200 characters
id int Unique ID of the pickup point
name i18n object Name – max 100 characters
position int Position – must be greater than 0
raw_address i18n object Raw address – max 200 characters

Impact

Project owners may set information about the impact of their project. In particular, project owners may set information about how their project addresses Sustainable Development Goals (SDGs) as defined by the United Nations. See https://sustainabledevelopment.un.org/ for more information.

Impact resource

Field Type Description
certifications i18n object Project labels and certifications
challenges i18n object Project challenges and risks
impact i18n object Project impact
sdgs array of project SDG resources Project SDGs

Project SDG resource

Field Type Description
description i18n object How the project addresses the SDG
id int Unique ID of the project SDG
sdg SDG resource SDG

SDG resource

Field Type Description
code string Code of the SDG
description i18n object Description of the SDG
logo i18n object where values are image resources Logo image of the SDG
title i18n object Title of the SDG, only shown for top level SDGs
targets array of SDG resources Targets of the SDG, only shown in the list SDGs endpoint

List SDGs

Retrieves all SDGs.

get /v1/sdgs

Retrieve project impact

Retrieves the impact of the project with the given ID.

get /v1/projects/:id/impact
Parameter Description
:id Project ID

Update project impact

Updates the impact of the project. This endpoint is only accessible to the project owner.

patch /v1/projects/:id/impact
Parameter Description
:id Project ID

Payload

Field Type Description
certifications i18n object Project labels and certifications – max 500 chars
challenges i18n object Project challenges and risks – required, max 500 chars
impact i18n object Project impact – required, max 500 chars

Also, it’s possible to create, update, and delete project SDGs with the following payload fields.

Field Type Description
create_sdgs array of create-project-sdg payloads Create project SDG
update_sdgs array of update-project-sdg payloads Update project SDGs – the project SDG id field must be set
delete_sdgs array of ints Delete project SDGs – the ints in the array must be existing project SDGs id fields

Create project SDG payload

Field Type Description
description i18n object How the project addresses the SDG
sdg_code string Code of the SDG

Update project SDG payload

Field Type Description
description i18n object How the project addresses the SDG
id int Unique ID of the project SDG

Analytics Tag

Project owners may add analytics tags to their project to collect data. At the time of writing, only Google Analytics, Facebook pixel and Twitter are supported.

Analytics tag resource

Field Type Description
id int Unique ID of the tag
tag string Tag value
type string Tag type, can be facebook, google, twitter

Create an analytics tag

Creates a new analytics tag for the project with the given ID. This endpoint is only accessible to the project owner.

post /v1/projects/:id/analytics
Parameter Description
:id Project ID

Payload

Field Type Description
tag string Tag value – required
type string Tag type, can be facebook, google, twitter – required

Update an analytics tag

Updates the analytics tag with the given ID. This endpoint is only accessible to the project owner.

patch /v1/analytics/:id
Parameter Description
:id Analytics tag ID

Payload

Field Type Description
tag string Tag value
type string Tag type, can be facebook, google, twitter

Delete an analytics tag

Deletes the analytics tag with the given ID. This endpoint is only accessible to the project owner.

delete /v1/analytics/:id
Parameter Description
:id Analytics tag ID

List project analytics tag

Retrieves all the analytics tags that belong to the project with the given ID. This endpoint is only accessible if the project status is online, or if the authenticated user is the project owner.

get /v1/projects/:id/analytics
Parameter Description
:id Project ID

Account

The account resource is where project owners declare their legal status and bank details in order to get the funds after their project has been successfully funded.

The typical workflow is the following:

  1. Create an account.
  2. Update the project account_id.
  3. Let the project owner visit the edit account page at edit_url and fill all the required fields.

The web page behind edit_url can be customized with the logo_url and return_url url parameters.

Account resource

Field Type Description
birthday string Birthday of the account owner user, with format YYYY-MM-DD
country string Two-letter ISO code of the account country
edit_url string Link to the edit account page
email string Email of the account owner user
entity_name string Entity name of the account owner
first_name string First name of the account owner
id int Unique ID of the account
is_completed bool Must be true for a project owner to submit a project. This field is set to true when all required field in the edit account page has been filled
last_name string Last name of the account user
nationality string Two-letter ISO code of the nationality of the account owner
status string Status of the account, can be waiting, succeeded, failed, cancelled, processing
type string Legal entity type, can be business, association, personal

Retrieve an account

Retrieves the account with the given ID. This endpoint is only accessible to the account user.

get /v1/accounts/:id
Parameter Description
:id Account ID

Create an account

Creates an account for the user with the given ID.

post /v1/users/:id/accounts
Parameter Description
:id User ID

Payload

Field Type Description
birthday string Birthday of the user – required, with format YYYY-MM-DD
country string Country of the account – required, two-letter ISO 31661-code
currency string Currency of the account – optional, three-letter ISO code of the currency
email string Email of the user – required, max 254 characters
entity_name string Entity name of the account owner – required if entity type is business or association, max 250 characters
first_name string First name of the user – required, must be between 1 and 250 characters
last_name string Last name of the user – required, must between 1 and 250 characters
nationality string Nationality of the user – required, two-letter ISO 31661-code
type string Legal entity type – optional, must be one of business, association, personal, default is personal

List user accounts

Retrieves all the accounts owned by the user with the given ID. This endpoint is only accessible to oneself.

get /v1/users/:id/accounts
Parameter Description
:id User ID

News

Project owners may add news to their project to keep the crowd updated during and after the funding campaign.

The news status field can have the following values:

Status Description
online The news is online
waiting The news is not sent

News resource

Field Type Description
absolute_url string Link to the news on the Ulule website
author user resource Author of the news, only present in the news-detail endpoint
comments_count int Count of news comments
content i18n object Content of the news
date_creation string Date at which the news was created, with RFC 3339 format, only accessible to the news author
date_publication string Date at which the news was published, with RFC 3339 format, null if the news is not published
id int Unique ID of the news
project project resource Project the news belongs to, only present in the news-detail endpoint
reserved bool Whether the content is only visible to supporters
resource_uri string URL of the news resource
slug string Slug of the news
status string Status of the news, can be onlineor waiting
title i18n object Title of the news

The field permissions is present in the following endpoints:

Fields Possible values
self update

Retrieve a news

Retrieves the news resource with the given ID. This endpoint is only accessible if the news status is online, or if the authenticated user is the project owner.

get /v1/news/:id
Parameter Description
:id News ID

Create a project news

Creates a news for the project with the given ID. This endpoint is only accessible to the project owner.

post /v1/projects/:id/news
Parameter Description
:id Project ID

Payload

Field Type Description
content i18n object Content of the news – required
reserved bool Whether the content is only visible to supporters – optional, default is false
title i18n object Title of the news – required, max 255 characters

Update a news

Updates the news with the given ID. This endpoint is only accessible to the project owner.

patch /v1/news/:id
Parameter Description
:id News ID

Payload

Field Type Description
content i18n object Content of the news
reserved bool Whether the content is only visible to supporters
title i18n object Title of the news – max 255 characters

Delete a news

Deletes the news with the given ID. This endpoint is only accessible to the project owner. Status must be waiting.

delete /v1/news/:id
Parameter Description
:id News ID

List project news

Retrieves all the news resources that belong to the project with the given ID. This endpoint is only accessible if the project status is online, or if the authenticated user is the project owner.

get /v1/projects/:id/news
Parameter Description
:id Project ID

Query parameters

The list can be filtered with the following query parameters:

Parameter Description
status News status – value waiting is only accessible to project owner

Test a news

Sends an email to the author of the news with the given ID. This endpoint is only accessible to the news author.

The purpose of this endpoint is for the news author to see how the news looks like inside an email.

post /v1/news/:id/try
Parameter Description
:id News ID

Publish a news

Publishes the news with the given ID. This endpoint is only accessible to the project owner.

The news status must be waiting.

This endpoint does two things: it sets the news status to online and sends the news via email to every supporters of the project.

post /v1/news/:id/publish
Parameter Description
:id News ID

Unpublish a news

Unpublishes the news with the given ID. This endpoint is only accessible to the project owner.

The news status must be online.

post /v1/news/:id/unpublish
Parameter Description
:id News ID

Event

Various events related to the same project can be fetched together.

Event types

Type Description
first_order The first order of a project has been created.
news A news has been published.
percent_raised A project has reached X00% of its goal.
project_end A project has ended.
project_start A project has started.
sponsorship A sponsorship has been created.

Event resource

Field Type Description
data depends on type Event data
time string Date at which the event occurred, with RFC 3339 format
type string Type of the event, must be one of the available event types

List project events

Retrieves all the events of a project.

The response is paginated.

This endpoint also accepts the with_draft_news=true parameter, which adds the 3 most recent draft news to the response. This parameter is only accessible to the project owner.

get /v1/projects/:id/events
Parameter Description
:id Project ID

Comment

Users may post comments on projects and news, and also reply to comments. We currently support only one level of replies: it’s possible to reply to a parent comment, but it’s not possible to reply to a reply comment.

Comment resource

Field Type Description
comment string Body of the comment
id int Unique ID of the tag
replies_count int Count of the comment replies, only present if the comment is a parent comment
replies array of comment resources Replies to the comment, only present if the comment is a parent comment
submit_date_formatted string Relative date of the comment submission
submit_date string Date of the comment submission, with RFC 3339 format
user user resource Author of the comment

Create a project comment

Creates a comment on the project with the given ID.

post /v1/projects/:id/comments
Parameter Description
:id Project ID

Payload

Field Type Description
comment string Body of the comment – required, max 500 characters

Create a news comment

Creates a comment on the news with the given ID.

post /v1/news/:id/comments
Parameter Description
:id News ID

Payload

Field Type Description
comment string Body of the comment – required, max 500 characters

Create an order comment

Creates a comment on the order with the given ID.

post /v1/orders/:id/comment
Parameter Description
:id Order ID

Payload

Field Type Description
comment string Body of the comment – required, max 500 characters

Create a reply to a comment

Creates a reply to the comment with the given ID. The comment must be a parent comment.

post /v1/comments/:id/replies
Parameter Description
:id Comment ID

Payload

Field Type Description
comment string Body of the comment – required

Update a comment

Updates the comment with the given ID. This endpoint is only accessible to the comment author.

patch /v1/comments/:id
Parameter Description
:id Comment ID

Payload

Field Type Description
comment string Body of the comment – required

Delete a comment

Deletes the comment with the given ID. This endpoint is only accessible to staff.

delete /v1/comments/:id
Parameter Description
:id Comment ID

List project comments

Retrieves all the comments on the project with the given ID.

get /v1/projects/:id/comments
Parameter Description
:id Project ID

List news comments

Retrieves all the comments on the news resource with the given ID.

get /v1/news/:id/comments
Parameter Description
:id News ID

List comment replies

Retrieves all the replies to the comment with the given ID.

The response is paginated.

get /v1/comments/:id/replies
Parameter Description
:id Comment ID

Export

Project owners can export data about their projects, typically for bookkeeping.

At the time of writing, only exports of type orders are available. The export file format can be csv or xlsx.

The typical workflow is the following:

  1. The project owner creates an export.
  2. The export is created asynchronously. Its status goes from waiting to processing to succeeded, it can also be failed or cancelled by the staff.
  3. The project owner receives an email with the export file attached.

Export resource

Field Type Description
created_at string Date at which the export has been created, with RFC 3339 format
format string File format, can be csv or xlsx
id int Unique ID of the export
project_id int Unique ID of the related project
status string Status of the export, can be one of waiting, succeeded, failed, canceled, processing
type string Type of the export
url string URL of the file
user user resource Recipient of the export

Retrieve an export

Retrieves the export with the given ID. This endpoint is only accessible to the owner of the related project.

get /v1/exports/:id
Parameter Description
:id Export ID

Create an export

Creates an export for the project with the given ID. This endpoint is only accessible to the project owner.

post /v1/projects/:id/exports
Parameter Description
:id Project ID

Payload

Field Type Description
format string Format of the export – required, must be csv or xlsx
type string Type of the export – required, must be orders
columns export columns object Columns to be exported, and their header names – optional, by default all columns are included

Export columns

The export columns object is a JSON object whose keys are the columns to be exported, and whose values are the headers of each column in the export.

For example, if the columns payload field has the following value, the export only includes the order ID, the user email and the reward description, with the given header values.

{
    "columns": {
        "order.id" : "ID de la commande",
        "user.email": "Email de l'utilisateur",
        "order.reward.description": "Description de la contrepartie"
    }
}

The available columns are the following:

  • order.id
  • user.username
  • user.lang
  • user.full_name
  • user.email
  • shipping_address.first_name
  • shipping_address.last_name
  • shipping_address.entity_name
  • shipping_address.address_1
  • shipping_address.address_2
  • shipping_address.postal_code
  • shipping_address.city
  • shipping_address.state
  • shipping_address.country
  • billing_address.first_name
  • billing_address.last_name
  • billing_address.entity_name
  • billing_address.type
  • billing_address.address_1
  • billing_address.address_2
  • billing_address.postal_code
  • billing_address.city
  • billing_address.state
  • billing_address.country
  • order.reward.id
  • order.reward.description
  • order.reward.price
  • order.reward.quantity
  • order.reward.total
  • order.total
  • order.tracking.source
  • order.tracking.medium
  • order.payment_method
  • order.status
  • order.created_at
  • order.note

List project exports

Retrieves all the exports related to the project with the given ID. This endpoint is only accessible to the owner of the related project,

The response is paginated.

get /v1/projects/:id/exports
Parameter Description
:id Project ID

Order

The order status field can have the following values:

Status Description
processing The order is processing
awaiting-confirmation The user is filling payment information
payment-completed The order is completed
cancelled The user has cancelled the order during the campaign
payment-done The order was completed, the campaign succeeded and the funds were successfully transferred to the project owner account
payment-invalid The order was completed, the campaign succeeded but the funds couldn’t be transferred to the project owner account
payment-reimbursed The order was completed but the campaign has failed, so the backer has been reimbursed
error An error has occurred

Order resource

Field Type Description
absolute_url string Link to the order on the Ulule website
billing_address address resource Billing address
created_at string Date at which the order has been created, with RFC 3339 format
id int Unique ID of the order
is_preauthorization bool Whether the order is a preauthorization.
items array of order item resources Order items
note string Free field that the backer can fill to give special information to the project owner about the order
order_shipping_total int Total shipping cost
order_subtotal int Cost of the order, minus the shipping cost
order_total int Total cost
payment_method string Payment method used for the order – can be one of the available payment methods
payment_url string URL that the backer must visit to fill payment information
pickup_point pickup point resource Pickup point
project project resource Project related to the order
project_id int Unique ID of the related project
refunded bool True if the order was refunded
resource_uri string URL of the order resource
shipping_address address resource Shipping address
shipping_type string Shipping type, can be pickup_point, user_address, no_shipping
status string Status of the order, can be processing, awaiting-confirmation, payment-completed, cancelled, payment-done, payment-invalid, payment-reimbursed, error
tip float Difference between the order total and the sum of each order item total with shippings included
user user resource Author of the order

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
latest_user_project_comment comment resource Latest comment the order user posted on the order project – only accessible on the projects.orders_list endpoint
project.analytics array of analytics tags Order project analytics tags
project.partnerships array of partnerships Partnerships of the order project
project.sponsorships array of sponsorships Sponsorships of the order project
tracking order tracking resource Order tracking – only accessible to the order project owner

Order item resource

Field Type Description
line_shipping_total int Total shipping cost
line_subtotal int Cost of the item, minus the shipping cost
line_total int Total cost of the item
quantity int Number of reward item
reward reward resource Reward item
reward_id int Unique ID of the reward item
unit_price int Price of a single reward item

Order tracking resource

Field Type Description
medium string Order tracking medium
source source Order tracking source

Retrieve an order

Retrieves the order with the given ID. This endpoint is only accessible to the order author.

get /v1/orders/:id
Parameter Description
:id Order ID

Create an order

Creates an order for the project with the given ID.

post /v1/projects/:id/orders
Parameter Description
:id Project ID

Payload

Backers have two choices:

  1. Set the order amount to a value greater than or equal to the project lowest contribution amount.
  2. Select project rewards and optionally set the order amount to a value greater than or equal to the sum of each reward price.
Field Type Description
amount int Order amount – optional, must be greater than or equal to the sum of each selected reward price if rewards is present, or to the project lowest contribution amount otherwise
billing_address address payload Billing address created with the order – optional, must not be set with billing_address_id
billing_address_id int Billing address ID – optional
payment_method string Payment method – required, must be a payment method supported by the project
pickup_point_id int Pickup point ID – optional, must be a project pickup point
return_url string URL at which the backer will be redirected after payment – optional
rewards array of reward items Selected rewards – optional
shipping_address address payload Shipping address created with the order – optional, must not be set with shipping_address_id
shipping_address_id int Shipping address ID – optional

If the order has shippings (that is, if one or more of the selected reward has shippings), one of shipping_address, shipping_address_id and pickup_point_id is required.

Reward items

Field Type Description
reward_id int Unique ID of the reward – required, must be a project reward
quantity int Reward quantity – required, must be less than or equal to the reward stock_available field

Update an order

Updates the order with the given ID. This endpoint is only accessible to the order author.

patch /v1/orders/:id
Parameter Description
:id Order ID

Payload

Field Type Description
hidden bool Whether the order project is shown or hidden in the user supported project list
note string A note from the backer to the project owner about this order
user_id int The ID of the new owner of the order – only accessible to staff

Cancel an order

Cancels the order with the given ID. This endpoint is only accessible to the order author.

The following conditions must be fulfilled to cancel an order:

  • The project must not be finished and succeeded
  • Only orders with payment-completed status can be cancelled
post /v1/orders/:id/cancel
Parameter Description
:id Order ID

List user orders

Retrieves all orders belonging to the user with the given ID. This endpoint is only accessible to oneself.

The response is paginated.

get /v1/users/:id/orders
Parameter Description
:id User ID

Query parameters

The list can be filtered with the following query parameters:

Parameter Description
project_id Project
status Order status

List project orders

Retrieves all orders belonging to the project the given ID. This endpoint is accessible anonymously.

To show private data from anonymous users, project owners may use the ?show_anonymous=true query parameter.

The response is paginated.

get /v1/projects/:id/orders
Parameter Description
:id Project ID

Query parameters

The list can be filtered with the following query parameters:

Parameter Description
payment_method Order payment method
reward_id Order reward ID
status Order status

Address

Backers may be required to create addresses to be used with orders.

Address resource

Field Type Description
address1 string First line of the address
address2 string Second line of the address
city string City name
country string Two-letter ISO code of the country
entity_name string Entity name
first_name string First name of the address owner
id int Unique ID of the address
last_name string Last name of the address owner
phone_number string Phone number
postal_code string Postal Code
state string State
type string Legal entity type, can be personal, business, association
user_id int Unique ID of the address owner

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
has_shippings bool Whether the address is the shipping address of an order with shipping

Retrieve an address

Retrieves the address with the given ID. This endpoint is only accessible to the address owner.

get /v1/addresses/:id
Parameter Description
:id Address ID

Create an address

Creates an address for the user with the given ID. This endpoint is only accessible to oneself.

post /v1/users/:id/addresses
Parameter Description
:id User ID

Payload

Field Type Description
address1 string First line of the address – required, max 255 characters
address2 string Second line of the address – optional, max 255 characters
city string City – required, max 140 characters
country string Country – required, two-letter ISO code
entity_name string Entity name – required if type is business or association, max 250 characters
first_name string First name – required if type is personal, max 30 characters
last_name string Last name – required if type is personal, max 30 characters
phone_number string Phone number – optional, max 20 characters
postal_code string Postal code – required, max 140 characters
state string State – optional, max 255 characters
type string Type – required, must be personal, business or association

Update an address

Updates the address with the given ID. This endpoint is only accessible to the address owner.

patch /v1/addresses/:id
Parameter Description
:id Address ID

Payload

Field Type Description
address1 string First line of the address – max 255 characters
address2 string Second line of the address – max 255 characters
city string City – max 140 characters
country string Country – two-letter ISO code, must not be updated if address has shippings
entity_name string Entity name – max 250 characters
first_name string First name – max 30 characters
last_name string Last name – max 30 characters
phone_number string Phone number – max 20 characters
postal_code string Postal code – max 140 characters
state string State – max 255 characters
type string Type – personal, business or association

Delete an address

Deletes the address with the given ID. This endpoint is only accessible to the address owner.

delete /v1/addresses/:id
Parameter Description
:id Address ID

List user addresses

Retrieves all the addresses owned by the user with the given ID. This endpoint is only accessible to oneself.

get /v1/users/:id/addresses
Parameter Description
:id Address ID

Query parameters

The list can be filtered with the following query parameters:

Parameter Description
country The address country

Proposal

To launch a project on the Ulule platform, users must first go through the proposal process.

The proposal status can have the following values:

Status Description
pending The proposal is pending for more information from the user
new The proposal is ready to be evaluated by the moderation team
valid The moderation team has accepted the proposal
invalid The moderation team has refused the proposal
waiting The moderation team has suspended the proposal, it must be updated by the user
updated The user has updated the proposal

Only proposals with status new are inspected by the moderation team. For a proposal status to be new, the proposal must not be anonymous and the following fields must be filled:

  • description
  • rewards or rewards_type
  • country
  • currency
  • lang
  • nb_products_min if the type is presale or goal if the type is project or goal_range

Proposal resource

Field Type Description
address string Address of the proposal user
answer string Answer from the moderation team in raw text
answer_html string Answer from the moderation team in HTML format – if answer_html is empty, fallback to answer
category category resource Category
category_id int Unique ID of the category
city string City
country string Two-letter ISO code of the country
currency string Three-letter ISO code of the currency
date_creation string Date at which the proposal has been created, with RFC 3339 format
date_start_estimation string Estimation of the date of the beginning of the founding campaign – can be one of as soon as possible, in the month, in one to three months, in more than three months
date_update string Date at which the proposal has been last updated, with RFC 3339 format
description string Description of the proposal
email string Email of the proposal user
first_name string First name of the proposal user
goal int Minimum amount the project must raise to succeed
goal_range goal range resource Maximum and/or minimum amount the project owner needs to collect
id int Unique ID of the proposal
lang string Language of the proposal
last_name string Last name of the proposal user
legal_entity_type string Legal entity of the proposal user – can be one of personal, business, association
manager user resource Manager assigned to the proposal – only visible to staff
name string Name of the proposal
nb_products_min int Minimum number of presales the project must receive to succeed
partner partner resource Partner of the proposal
phone_number string Phone of the proposal user
project project resource Project created from the proposal
references string References of the proposal
resource_uri string URL of the proposal resource
rewards string Description of the rewards of the proposal
rewards_type string Rewards type of the proposal – can be one of concrete, symbolic, financial, none, undefined
score int Score of the proposal – only visible to staff
score_entries score entries resource Score entries of the proposal – only visible to staff
status string Current status of the proposal – can be one of pending, new, valid, invalid, waiting, updated
structure string Structure of the proposal user
token string Automatically generated token that can be used to retrieve an anonymous proposal
type string Type of the proposal, can be presale or project
user user resource User who created the proposal

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
links array of links Links attached to the proposal
project.links array of links Links attached to the proposal project
project.tags array of tags Tags of the proposal project
user.stats user stats resource Stats of the proposal user – only accessible to staff

Goal range

Field Type Description
min int Minimum amount the project owner needs to collect – optional
max int Maximum amount the project owner needs to collect – optional

Score entries

Field Type Description
description int Score of the proposal description
goal_range int Score of the proposal goal range
legal_entity_type int Score of the proposal legal entity type
links int Score of the proposal links
rewards_type int Score of the proposal rewards type
user int Score of the proposal user

Retrieve a proposal

Retrieves the proposal with the given ID or token. This endpoint is only accessible to the proposal user if the path parameter is the proposal ID, and it is anonymously accessible if the path parameter is the proposal token.

get /v1/proposals/(:id)
get /v1/proposals/(:token)
Parameter Description
:id Proposal ID
:token Proposal token

Create a proposal

Creates a proposal. The POST /proposals endpoint is anonymously accessible. In case a user is authenticated, he or she automatically owns the created proposal. The POST /users/:id/proposals is only accessible to the user with the given ID, who automatically owns the created proposal.

post /v1/proposals
post /v1/users/:id/proposals

Parameter Description
:id User ID

Payload

Field Type Description
address string Address – optional
birthday string User birthday – optional, format YYYY-MM-DD
city string City – optional, max 255 characters
country string Country – required, two-letter ISO code of the country
currency string Currency – optional, three-letter ISO code of the currency
description string Description – optional
email string User email – required for anonymous proposal
first_name string User first name – optional, max 30 characters
goal int Amount the project must raised – optional
goal_range goal range payload Maximum and/or minimum amount the project owner needs to collect – optional
lang string Language – optional
last_name string User last name – optional, max 30 characters
legal_entity_type string User legal entity type – optional, can be one of personal, business, association
links array of strings References – optional
link_ids array of ints IDs of links related to the project and/or the project owner. The links must have been uploaded via the create-link endpoint and must not be already attached to a proposal – optional
name string Proposal name – optional, max 255 characters
nationality string User nationality – optional, two-letter ISO code of the nationality
nb_products_min int Minimum number of presales the project must receive – optional if type is presale
phone_number string Phone of the proposal user – optional, max 15 characters
rewards string Description of the rewards – optional
rewards_type string Type of rewards – optional, can be one of concrete, symbolic, financial, none, undefined
structure string Structure – optional, max 150 characters
type int Project type – optional, 1 for presale, 2 for project

Update proposal

Updates the proposal with the given ID or token. This endpoint is only accessible to the proposal user if the path parameter is the proposal ID, and it is anonymously accessible if the path parameter is the proposal token.

patch /proposals/:id
patch /proposals/:token

Parameter Description
:id Proposal ID
:token Proposal token

Payload

Field Type Description
address string Address
birthday string User birthday – format YYYY-MM-DD
country string User country – two-letter ISO code of the country
currency string Currency – three-letter ISO code of the currency
description string Description
email string User email
first_name string User first name – max 30 characters
goal int Amount the project must raised
lang string Language
last_name string User last name – max 30 characters
links array of strings References
name string Proposal name – max 255 characters
nationality string User nationality – two-letter ISO code of the nationality
nb_products_min int Minimum number of presales the project must receive
phone_number string Phone of the proposal user
rewards string Description of the rewards
structure string Structure – max 150 characters
type int Project type – 1 for presale, 2 for project

List user proposals

List all the proposals of the user with the given ID. This endpoint is only accessible to oneself.

The response is paginated.

get /v1/users/:id/proposals
Parameter Description
:id User ID

Query parameters

Parameter Description
status Status, must be one of new, valid orinvalid

List partner proposals

List all the proposals of the partner with the given slug. This endpoint is only accessible to staff.

The response is paginated.

get /v1/partners/:slug/proposals
Parameter Description
:slug Partner slug

Query parameters

Parameter Description
status Status, must be one of new, valid orinvalid

List the references of the proposal with the given ID. This endpoint is only accessible to the proposal user.

get /v1/proposals/:id/links
Parameter Description
:id Proposal ID

Resource

Field Type Description
id int Unique ID of the reference
url string URL of the reference

List proposals

List all proposals. By default, this endpoint list all proposals with status new. This endpoint is only accessible to staff.

The response is paginated.

get /v1/proposals

Query parameters

Parameter Description
country Country
lang Lang
status Status, must be one of new, valid, invalid, pending, updated or waiting
partner_id Partner ID

Validate Proposal

Validates the proposal with the given ID. It changes the proposal status to valid and creates a new project from the proposal. This endpoint is only accessible to staff.

post /v1/proposals/:id/validate
Parameter Description
:id Proposal ID

Payload

One of the answer and answer_html fields must be present in the payload.

Field Type Description
answer string Answer from the moderation team in raw text
answer_html string Answer from the moderation team in HTML format

Refuse Proposal

Refuses the proposal with the given ID. It changes the proposal status to invalid. This endpoint is only accessible to staff.

post /v1/proposals/:id/refuse
Parameter Description
:id Proposal ID

Payload

One of the answer and answer_html fields must be present in the payload.

Field Type Description
answer string Answer from the moderation team in raw text
answer_html string Answer from the moderation team in HTML format

Suspend Proposal

Suspends the proposal with the given ID. It changes the proposal status to waiting. This endpoint is only accessible to staff.

post /v1/proposals/:id/suspend
Parameter Description
:id Proposal ID

Payload

One of the answer and answer_html fields must be present in the payload.

Field Type Description
answer string Answer from the moderation team in raw text
answer_html string Answer from the moderation team in HTML format

Partner

Partner resource

Field Type Description
id int Unique ID of the partner
logo image resource Partner logo
name string Partner name
ribbon image resource Partner ribbon
slug string Unique slug of the partner
url string Link to the partner website
user_id int Unique ID of the partner user

Retrieve a partner

Retrieves the partner with the given ID.

get /v1/partners/:id
Parameter Description
:id Partner ID

Partnership

Partnership resource

Field Type Description
id int Unique ID of the partnership
is_default bool If true, the partner is the default one for the project
is_support bool
partner partner resource Partner
project project resource Project

Retrieve a partnership

Retrieves the partnership with the given ID. This endpoint is only accessible to partner users.

get /v1/partnerships/:id
Parameter Description
:id Partnership ID

Create a project partnership

Creates a new partnership for the project with the given ID. This endpoint is only accessible to staff.

post /v1/projects/:id/partnerships
Parameter Description
:id Project ID

Payload

Field Type Description
partner_id int Unique ID of the partner – required
is_default bool
is_support bool

Update a partnership

Updates the partnership with the given ID. This endpoint is only accessible to staff.

patch /v1/partnerships/:id
Parameter Description
:id Partnership ID

Payload

Field Type Description
is_default bool
is_support bool

Delete a partnership

Deletes the partnership with the given ID. This endpoint is only accessible to staff.

delete /v1/partnerships/:id
Parameter Description
:id Partnership ID

List project partnerships

Retrieves all the partnerships of a project. This endpoint is only accessible to the project owner and the partner users.

get /v1/projects/:id/partnerships
Parameter Description
:id Project ID

Sponsorship

Projects can have up to 4 sponsorships.

Sponsorship resource

Field Type Description
amount int Amount of the sponsorship
coefficient int Coefficient of the sponsorship
description i18n object Main description of the sponsorship
id int Unique ID of the sponsorship
is_full bool True if the total amount is reached
main_color string Main color of the sponsorship – HEX format
priority int Priority of the sponsorship
project_id int Unique ID of the project
sponsor sponsor resource Sponsor

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
channel channel resource Channel
Field Type Description
id int Unique ID of the sponsor
image image resource Image of the sponsor
link string Link to the sponsor website
name string Name of the sponsor
position int
type string Type of the sponsor (normal or premium)
user user resource User of the sponsor

List project sponsorships

Retrieves all the sponsorships of a project.

get /v1/projects/:id/sponsorships
Parameter Description
:id Project ID

Channel

Channel resource

Field Type Description
absolute_url string Link to the channel page on the Ulule website
background image resource Background image of the channel
created_at string Date at which the channel has been created, with RFC 3339 format
description i18n object Description of the channel
logo image resource Logo image of the channel
name i18n object Name of the channel
partner partner resource Partner of the channel
position int Position of the channel
slug string Unique slug of the channel
subtitle i18n object Subtitle of the channel
updated_at string Date at which the channel has been updated, with RFC 3339 format
user user resource User who created the channel

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
featured_project project resource Featured project
is_subscribed bool Whether the authenticated user is subscribed to the channel
links array of channel link resources Channel links
Field Type Description
cta_label i18n object CTA label of the link
description i18n object Description of the link
image image resource Image of the link
name i18n object Name of the link
url string URL of the link
video string Video of the link

List channels

List all channels.

The response is paginated.

get /v1/channels

Query parameters

Parameter Description
country Country
lang Lang
project_id Project ID

Retrieve a channel

Retrieves the channel with the given slug.

get /v1/channels/:id
Parameter Description
:slug Channel slug

List user channels

List channels for the user with the given ID.

The response is paginated.

get /v1/users/:id/channels
Parameter Description
:id User ID

Channel subscriptions

Users can subscribe to channels to receive weekly notifications about new projects from the subscribed channels.

Subscribe to a channel

POST /v1/channel/:id/subscribe where :id is the channel ID or slug.

Unsubscribe to a channel

POST /v1/channel/:id/unsubscribe where :id is the channel ID or slug.

Project FAQ

A list of frequently asked questions (FAQ) can be attached to a project.

Project FAQ resource

Field Type Description
answer_author user resource User who answered the question
answer i18n object Answer
id int Unique ID of the FAQ
question_author user resource User who asked the question
question i18n object Question

List project FAQ

List all frequently asked questions for the project with the given id.

The response is paginated.

get /v1/projects/:id/faq
Parameter Description
:id Project ID

Create project FAQ

Creates a new FAQ.

post /v1/projects/:id/faq
Parameter Description
:id Project ID

Payload

Field Type Description
question i18n object Question – required, must contain only one lang and a text with 500 characters max

Member

Project owners may add members to their project. Project members have one of two roles: editor means the user may update the project, moderator means there’s a label next to the user’s comments.

Member resource

Field Type Description
date_creation string Date at which the member has been added to the project, with RFC 3339 format
id int Unique ID of the member
role string Role of the member
user user resource User resource

Create a member

Creates a new member. This endpoint is only accessible to the project owner.

post /v1/projects/:id/members
Parameter Description
:id Project ID

Payload

Field Type Description
role string Role of the member – required, must be one of editor, moderator
username string Email or username of the user – required

Update a member

Updates the member with the given ID. This endpoint is only accessible to the project owner.

patch /v1/members/:id
Parameter Description
:id Member ID

Payload

Field Type Description
role string Role of the member – required, must be one of editor, moderator

Delete a member

Deletes the member with the given ID. This endpoint is only accessible to the project owner.

delete /v1/members/:id
Parameter Description
:id Member ID

List all project members

Retrieves all the members of the project. This endpoint is only accessible to the project owner.

get /v1/projects/:id/members
Parameter Description
:id Project ID

Slug

Projects may have multiple slugs, which redirect requests to the active project slug.

Slug resource

Field Type Description
id int Unique ID of the slug
slug string Value of the slug

Delete a slug

Deletes the slug with the given ID. This endpoint is only accessible to staff.

delete /v1/slugs/:id
Parameter Description
:id Slug ID

Webhooks

Webhooks allow partners to receive notifications about events happening on the Ulule platform.

When an event occurs, for example when a order succeeds, Ulule creates an Event object. This object contains all the relevant information, including the type of event and the URI of the resource associated with that event.

Ulule then sends the Event object in the body of an HTTP POST request to the registered URL of a partner.

Event object

An event object typically looks like the following:

{
    "created": "2015-09-01T16:40:05.805422",
    "object": "event",
    "resource": {
        "type": "project",
        "uri": "https://api.ulule.com/v1/projects/53423"
    },
    "type": "project.funded",
}

Configuring a server to receive webhooks

Configuring a server to receive webhooks is very close to creating a new page on a website.

With PHP, you might create a new .php file on your server. With a framework like Flask, you would add a new route with the desired URL.

Remember, with webhooks, your server is the server receiving the request.

Webhooks reference

Event type Description Resource type
user.created Occurs when a user is created user
user.updated Occurs when a user is updated user
avatar.updated Occurs when a user avatar changes user
project.created Occurs when a project is created project
project.updated Occurs when a project is updated project
project.submitted Occurs when a project is submitted to moderation by a project owner project
project.refused Occurs when the moderation team sets the project status to refused during the validation step project
project.published Occurs when a project is put online by the project owner or the moderation team project
project.unpublished Occurs when the moderation team puts a project offline project
project.funded Occurs when a project is successfully funded project
project.unfunded Occurs when a project ends without being successfully funded project
image.created Occurs when a image is created project
image.updated Occurs when a image is updated project
image.deleted Occurs when a image is deleted project
video.created Occurs when a video is created project
video.updated Occurs when a video is updated project
video.deleted Occurs when a video is deleted project
reward.created Occurs when a reward is created reward
reward.updated Occurs when a reward is updated, or a variant of this reward is created, updated or deleted reward
reward.deleted Occurs when a reward is deleted project
shipping.created Occurs when a shipping is created reward
shipping.updated Occurs when a shipping is updated reward
shipping.deleted Occurs when a shipping is deleted reward
news.created Occurs when a news is created news
news.updated Occurs when a news is updated news
news.published Occurs when a news is published news
news.deleted Occurs when a news is deleted news
news.unpublished Occurs when a news is unpublished news
comment.created Occurs when a comment is created can be project or news
order.completed Occurs when an order is completed order
order.cancelled Occurs when an order is cancelled order
order.reimbursed Occurs when an order is reimbursed order
order.updated Occurs when an order is updated order
proposal.created Occurs when a proposal is created proposal
proposal.validated Occurs when a proposal is validated by the moderation team proposal
proposal.refused Occurs when a proposal is refused by the moderation team proposal
message.sent Occurs when a message is sent in the discussion thread of a project message

Discussions

All discussions API access is over HTTPS, and accessed from the discussions.ulule.com/api endpoint.

Data is sent and received as JSON, except file uploads.

This separate API contains resources from Ulule API.

Thread

Thread resource

Field Type Description
created_at string Date of the thread creation, with RFC 3339 format
id int Unique ID of the thread
latest_message message resource Latest message of the thread
messages_count int Total count of the messages in thread
metadata json object Arbitrary object
recipients_count int Total count of the thread recipients
recipients array of user resources Recipients of the thread
sender_deleted_at string Date of the thread deletion, with RFC 3339 format, null if the thread is not deleted
sender_id int Unique ID of the sender
status string Status of the thread for the authenticated user, can be unread, read or deleted
subject string Subject of the thread
updated_at string Date of the last update of the thread, with RFC 3339 format

Retrieve thread list

Retrieves all the threads where the authenticated is a recipient, ordered by updated_at.

The response is paginated.

get /threads

Query parameters

Field Description
status Thread status – can be one of unread, read or deleted, default is the combination of read and unread)

Retrieve a thread

Retrieves the thread with the given ID. This endpoint is only accessible to the thread recipients.

get /threads/:id
Parameter Description
:id Thread ID

Update a thread

Updates the thread with the given ID. This endpoint is only accessible to the thread owner.

patch /threads/:id
Parameter Description
:id Thread ID

Payload

Field Type Description
metadata json object Arbitrary object
subject string Subject of the thread – min 3 characters, max 254 characters

Read a thread

Marks the thread with the given ID as read. This endpoint is only accessible to the thread recipients.

post /threads/:id/read
Parameter Description
:id Thread ID

Unread a thread

Marks the thread with the given ID as unread. This endpoint is only accessible to the thread recipients.

post /threads/:id/unread
Parameter Description
:id Thread ID

Unwatch a thread

Marks the thread with the given ID as deleted. The user won’t receive notifications if new messages are sent. This endpoint is only accessible to the thread recipients.

post /threads/:id/unwatch
Parameter Description
:id Thread ID

Leave a thread

Leaves the thread with the given ID. The user is removed from the thread recipients. This endpoint is only accessible to the thread recipients. The thread sender can’t leave a thread.

post /threads/:id/leave
Parameter Description
:id Thread ID

Bulk operation

Runs a bulk operation on a list of threads.

This endpoint allows user to perform the same operation on a bulk of threads.

The operation is atomic, i.e. if the operation fails for one thread in the list, it is a no-op for all threads.

post /threads/bulk

Payload

Field Type Description
operation string Operation to apply on threads – required, can be read, unread, unwatch or leave
thread_ids array of ints IDs of the threads to run the operation on

Recipient

Recipient resource

A recipient resource is a user resource.

List recipients of a thread

Retrieves recipients of the thread with the given ID. This endpoint is only accessible to the thread recipients.

post /threads/:id/recipients
Parameter Description
:id Thread ID

Message

The message status field can be either draft or sent. A draft message is only visible to its sender.

In case a user needs to add attachments to a message, the typical workflow is to first create a draft message, then create the attachments, and eventually send the message.

Message resource

Field Type Description
attachments list of attachment resource Attachments of the message
body string Body of the message in raw text and without HTML markup
body_html string Body of the message in HTML format – in case body_html is empty, fallback to body
id int Unique ID of the message
sender_deleted_at string Date of the message deletion, with RFC 3339 format, null if the message is not deleted
sender user resource Sender of the message
sent_at string Date at which the message has been sent, with RFC 3339 format
status string Status of the message, can be draft or sent
thread_id int Unique ID of the message thread
thread thread resource Thread of the message, only present in the message-detail endpoint

Create a message

Creates a message for the thread with the given ID. This endpoint is only accessible to the thread recipients.

post /threads/:id/messages
Parameter Description
:id Thread ID

Payload

One of the body and body_html fields must be present in the payload.

Field Type Description
body string Body of the message in raw text
body_html string Body of the message in HTML format
status string Status of the message – optional, can be sent or draft, default is sent

Update a message

Updates the message with the given ID. This endpoint is only accessible to the message sender.

patch /messages/:id
Parameter Description
:id Message ID

Payload

One of the body and body_html fields must be present in the payload.

Field Type Description
body string Body of the message in raw text
body_html string Body of the message in HTML format

Send a message

Sends the message with the given ID. This endpoint is only accessible to the message sender.

The message status must be draft.

post /messages/:id/send
Parameter Description
:id Message ID

List messages of a thread

Retrieves all the messages of the thread with the given ID, ordered by sent_at. This endpoint is only accessible to the thread recipients.

The response is paginated.

get /threads/:id/messages
Parameter Description
:id Thread ID

Attachment

Attachment resource

Field Type Description
created_at string Date at which the attachment has been created, with RFC 3339 format
file string URL of the attached file
id int Unique ID of the attachment
name string Name of the attached file

Create an attachment

Creates an attachment for the message with the given ID. This endpoint is only accessible to the message sender.

post /messages/:id/attachments
Parameter Description
:id Message ID

Payload

Field Type Description
file file File of the attachment – required, format must be one of jpg, png, gif, pdf, xlsx, xls, doc, docx, zip, ppt, pptx

Delete an attachment

Deletes the attachment with the given ID. This endpoint is only accessible to the sender of the message associated with the attachment.

delete /attachments/:id
Parameter Description
:id Attachement ID

Search

Search projects

The response is paginated.

get /v1/search/projects

Query parameters

Parameter Type Description
lang string Host language, for example it is the fr in fr.ulule.com. Results that are translated in that language are sorted first. Can be one of the supported languages
limit int Page size, default is 16
offset int Pagination offset, default is 0
q string Search keywords and qualifiers

The q query parameter may contain any combination of terms and of the following search qualifiers.

Qualifier Type Description
channel_ids array of ints Filter projects by channel
country string Filter projects by country
lang string Filter projects by language
owner_id int Filter projects by owner
partners array of strings Filter projects by partner – the qualifier may be suffixed with __not, which reverses the filter
quality_score array of strings Filter projects by quality score – must be one of A, B, C, X, the qualifier may be suffixed with __not, which reverses the filter
sort string Sort field – must be one of popular, amount, ending-soon, position or new, default is popular
status string Filter projects based on the goal status – must be one of currently, all, success or ended, default is all
tag_id int Filter projects by tag

Response

Field Type Description
projects project resource Search results

Search project resource

Field Type Description
absolute_url string Link to the project page on the Ulule website
amount_raised int Amount raised in project currency
country string Two-letter ISO code of the country
currency string Three-letter ISO code of the currency
date_end string Date at which the funding campaign ends, with RFC 3339 format
date_start string Date at which the funding campaign starts, with RFC 3339 format
finished bool True if the funding campaign is finished
goal int Goal in the project currency if type is project, or number of pre-orders if type is presale
id int Unique ID of the project
lang string Main language of the project
name i18n object Name of the project
nb_products_sold int Number of products sold
slug string Unique slug of the project
subtitle i18n object Subtitle of the project
type string Type of the project (presale or project)

The following fields are extra_fields and must be explicitly specified in the request:

Field Type Description
aggregations object Object whose fields are different project counts – only accessible to staff
answer_code string Answer from moderation team – only accessible to staff
main_image i18n object where values are image resources Main image of the project
main_tag tag resource Main tag of the project
manager user resource Manager of the project – only accessible to staff
moderator user resource User who moderated the project – only accessible to staff
owner user resource Owner of the project
owner.email string Email of the project owner – only accessible to staff
owner.stats user stats resource Stats of the project owner – only accessible to staff
proposal proposal resource Proposal from which the project was created – only accessible to staff
proposal.links array of links Links attached to the proposal – only accessible to staff
proposal.partner partner resource Partner of the proposal – only accessible to staff
quality_score string Quality score of the project – only accessible to staff
user_role string Relation between the project and the authenticated user, can be null, fan, supporter and owner – the request must be authentified

FAQ

When I visit a project page on the Ulule website, I see the following message: “This project was taken offline at the request of the project owner”. What does that mean and is there a corresponding field in the project resource?

Projects owners can decide to cancel their project at any time for any reason. In that case the project is still considered online (is_online in the project resource) but the content is not visible and there can be no orders.

The corresponding field in the project resource is is_cancelled.

How can project owners add images to their project description?

That’s what the images of type secondary are for.

The workflow is the following:

  1. Upload the image via the create image endpoint.
  2. Edit the project description via the update project endpoint, add the full version of the image.

Why is the reward.delivery_date field required?

We consider that when a project is launched on Ulule, it is a commitment for the project owner to deliver the rewards, even the symbolic ones.

What is the distinction between account.is_completed and account.status? Why allowing a project owner to submit a project when is_completed is set to true, but status is not yet succeeded?

is_completed is automatically set when the project owner has completed all required fields in the account form. status is automatically set when the account validation succeeds or fails.

The account validation process can take some time (~1 working day) and the project owner doesn’t have any progress information about it so it doesn’t make sense to forbid the project submission.

It is the role of the project manager to check the account form. The manager should wait for the account to be validated before validating the project. In case of an invalid account, the manager can ask the project owner to go back to the account form to edit the information.

It may be possible for a project to be validated and to go online before the account is validated, especially if the project owner wants to launch ASAP. This is up to the appreciation and judgement of the project manager.

How can a project owner remove the image field of an image of type background, to only have the background color?

Indeed it’s not possible to set the image field of a background image to null because the payload format is form-data. The way to go is to delete the image resource before creating a new one.

What happens if, during the campaign, a project owner wants to switch the account type, for example from individual to business?

It’s not possible for the project owner to create a new account if the project status is validated or online. In such a case, the project owner must ask to the project manager.

Why is the project.nb_products_sold field different from the sum of reward.stock_taken fields ?

For project of type presale, the nb_products_sold field is the number of orders. A baker can choose to create an order with any quantity of a reward.

About this documentation

This documentation is built with Hugo, and continuously deployed via netlify.

The source is hosted at https://github.com/ulule/developers.ulule.com.