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.

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.

The API version controls the API observable behavior, for example the fields present in resources, etc.

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 explicitely 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

2018-04-17

  • reward and variant resources
    • date_delivery format is YYYY-MM-DD instead of YYY-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

Authentication

In most of the 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 ways to authenticate through the API.

  • HTTP Basic
  • API key
  • OAuth2

To read private data, HTTP Basic and API key are usually enough. To write data, OAuth2 is required.

HTTP Basic

$ curl --user "username:password" "https://api.ulule.com/v1/..."

The username:password pair is the same authentication information used to log in to the Ulule website.

API Key

Instead of the username and password couple you can provide the API key which can be found in the account settings on the Ulule website.

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

OAuth2

The access_token will allow you to log as a user by passing it in each request.

You can pass it in each request as an authorization header:

$ curl -H "Authorization: Bearer USER-ACCESS-TOKEN" "https://api.ulule.com/v1/..."

Retrieve an access token

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

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

Request must be authenticated with the Basic method with the credentials being 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>" \
    -H "Authorization: basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXQ+" \
    https://www.ulule.com/oauth2/token/

where PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXQ+ is the base64 encoding of the <client_id>:<client_secret> string.

{
    "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://www.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 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 automatically authenticate the user on Ulule.

Refresh the access token

An access token expires after 10 hours.

Because you don’t store the user passwords in plain text in your database, you can’t generate a new access token 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://www.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 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 on Ulule.

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://www.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://www.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://www.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

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
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
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 Must be true for a user to contribute to a project. 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
personal_id_number string
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

Retrieve authenticated user

Retrieves the authenticated user.

get /v1/me

Retrieve a user

Retrieves the user with the given ID. This endpoint is only accessible to oneself and to staff users.

/v1/users/:id /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
username string Username – required, max 80 characters
password1 string Password of the user – required, max 128 characters
email string Email of the user – required, max 254 characters
lang string Language of the user – optional
ip_address string IP address of the user – optional

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
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
presentation i18n object Longer presentation of the user
screenname string Screenname of the user – max 30 characters
username string Username – max 80 characters

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

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.

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

Creates a new link for the user with the given ID. This endpoint is only accessible to oneself.

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

Payload

Field Type Description
url string URL of the link – required

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

patch /v1/links/:id
Parameter Description
:id Link ID

Payload

Field Type Description
url string URL of the link – required

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

delete /v1/links/:id
Parameter Description
:id Link ID

Retrieves all the links that belongs to the user with the given ID. This endpoint is only accessible to oneself.

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

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

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
account account resource
amount_raised int
analytics_count int
background image resource Background image or color 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
currency_display string Unicode character 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
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
finished bool True if the funding campaign ended
goal_raised bool True if the current sum collected is superior to the project goal
goal int Total sum in the given currency of the funds targeted by the campaign
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 image resource 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 Number of products sold
news_count int Count of news published
owner user resource Owner of the project
partnerships array of partnership resources Partnerships of the project, only present in the project-detail endpoint
payments_methods array of strings Payments methods supported by the project (check, creditcard, paypal, directdebit, maestro, ideal, saving, bankwire)
percent int Percentage of the goal raised on the goal targeted
resource_uri string URL of the project resource
rewards array of reward resources Rewards of the project
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 video resource Video of the project
visible bool

In addition, some fields are present only in certain conditions:

Field Type Description
fields_needed array of strings Project fields that must be filled by the project owner before the project can be submitted for validation to the moderation team, only present when the project is not online
notifications

Retrieve a project

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

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
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
name i18n object Name of the project
slug string Slug of the project, this field must be unique accross the platform and so can’t be updated to an already existing slug
subtitle i18n object Subtitle of the project
timezone string Timezone of the project

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
tags array of ints ID of tags related to the project

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

Field Type Description
comments_enabled string Enable comments, must be one of everyone, supporters and disabled
status string Project status
supporters_disabled string If set to false, the “Supporters” tab is not visible on the project page on Ulule website
type string Project type – must be project or presale
unread bool
visible bool If set to false, the project is not indexed by search engines

Submit a project

Submits the project for review to the moderation team. This endpoint is only accessible to the project owner.

The project status must be new.

Additionally, the following fields must be set (i18n fields must be set in the project default language):

  • country
  • currency
  • description
  • description_funding
  • description_yourself
  • goal (if type is project)
  • lang
  • name
  • nb_product_min (if type is presale)
  • owner.avatar
  • owner.email
  • owner.location
  • rewards
  • slug
  • subtitle
  • one of date_end anf nb_days

Finally, the account.is_completed field must be true

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

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

List all 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.

The response is paginated.

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

List user projects

Retrieves all the projects related to the user with the given ID. This endpoint is only accessible to oneself.

The response is paginated.

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

Query parameters

Parameter Description
state Allow to filter the type of relationship between the projects and the user. It can be one of created, followed, supported. By default, it returns all

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.

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

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 three different types 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

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 (main, secondary, background)
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
color string HTML hex color code – only used for images of type background
image file Image file – required for images of type main and secondary, format must be GIF, JPEG or PNG, size must be less than 5MB
lang string Image language – required
type string Image type (main, secondary, background) – required

Update an image

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

patch /v1/images/:id
Parameter Description
:id Image ID

Payload

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

Field Type Description
color string HTML hex color code – only used for images of type background
image file Image file – format must be GIF, JPEG or PNG, size must be less than 5MB
lang string Image language
type string Image type (main, secondary, background)

Delete an image

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

delete /v1/images/:id
Parameter Description
:id Image ID

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

The project owner can add a video to the project. The video will be displayed on the project page. A project can’t have more than one video per language.

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
value string
version string
width int

Create a project video

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

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

Payload

Field Type Description
language string Language of the video – required
url string URL of the video – required

Update a video

Updates a video. This endpoint is only accessible to the project owner.

patch /v1/videos/:id
Parameter Description
:id Video ID

Payload

Field Type Description
url string URL of the video

Delete a video

Deletes a video. This endpoint is only accessible to the project owner.

delete /v1/videos/:id
Parameter Description
:id Video ID

List project videos

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

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

Reward

Reward resource

Field Type Description
address_required bool The project owner can choose to set this field. If true, contributors must specify a shipping address when ordering the reward
available bool True if reward is available
date_delivery string Date of the reward delivery with the YYYY-MM-DD format. This field must be set by the project owner. It is only an estimation of the expected shipping delivery delay of the reward
description i18n object Description of the reward, can contain HTML tags
has_shippings bool True if the reward has shippings
id int Unique ID 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
shipping_int float International shipping cost, null if no shipping
shipping_nat float National shipping cost, null if no shipping
shippings array of shipping resources Per country shippings
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
variants array of variant resources

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 owner of the related project, but not when the project status is one of pending-final-validation, validated and online. The idea behind that restriction is that it’s not possible for a project owner to add more rewards to the project after it has been validated by the moderation team.

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

Payload

Field Type Description
address_required bool If true, contributors must specify a shipping address when ordering the reward – optional, default is false
date_delivery string Date of the reward delivery with the YYYY-MM-DD format – required
description i18n object Description – required
price float Price – required, must be between 0 and 1e10
shipping_int float International shipping cost – optional
shipping_nat float National shipping cost – optional
stock int Stock – optional

Update a reward

Updates the reward with the given ID. This endpoint is only accessible to the owner of the related project and if the project is not finished.

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

Payload

Field Type Description
address_required bool If true, contributors must specify a shipping address when ordering the reward
date_delivery string Date of the reward delivery with the YYYY-MM-DD format
description i18n object Description
price float Price, must be between 0 and 1e10
shipping_int float International Shipping
shipping_nat float National Shipping
stock int Stock

Delete a reward

Deletes the reward with the given ID. This endpoint has the same restriction as the create-reward endpoint.

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

Variant

Variant resource

The variant resource is almost the same as the reward resource. It has no has_shippings, shipping_int, shipping_nat, shippings fields, as a variant always has the same shipping costs as its parent reward. It also has no variants field.

Create a reward variant

Creates a new variant for the reward with the given ID. This endpoint has the same limitations as the create-reward endpoint.

post /v1/rewards/:id/variants
Parameter Description
:id Reward ID

Payload

Field Type Description
date_delivery string Date estimated for the delivery with the YYYY-MM-DD format – optional
description i18n object Description – required
stock int Stock – optional

Update a variant

Updates the variant with the given ID. This endpoint has the same limitations as the update-reward endpoint.

patch /v1/variants/:id
Parameter Description
:id Variant ID

Payload

Field Type Description
date_delivery string Date estimated for the delivery with the YYYY-MM-DD format
description i18n object Description
stock int Stock

Delete a variant

Deletes the variant with the given ID. This endpoint has the same limitations as the delete-reward endpoint.

delete /v1/variants/:id
Parameter Description
:id Variant ID

List reward variants

Retrieves all the variants that belong to 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.

The response is paginated.

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

Shipping

Shipping resource

Field Type Description
amount float Shipping cost
countries array of strings Array of countries, represented by their two-letter ISO code
id int Unique ID of the shipping

Create a reward shipping

Creates a new shipping for the reward with the given ID. This endpoint has the same limitations as the create-reward endpoint.

post /v1/rewards/:id/shippings
Parameter Description
:id Reward ID

Payload

Field Type Description
amount float Shipping cost – can be between 0 and 999.99, default is 0
countries array of strings Countries, represented by their two-letter ISO code – required, must contain at least one country

Update a shipping

Updates the shipping with the given ID. This endpoint has the same limitations as the update-reward endpoint.

patch /v1/shippings/:id
Parameter Description
:id Shipping ID

Payload

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

Delete a shipping

Deletes the shipping with the given ID. This endpoint has the same limitations as the delete-reward endpoint.

delete /v1/shippings/:id
Parameter Description
:id Shipping ID

List reward shippings

Retrieves all the shippings that belong to 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/shippings
Parameter Description
:id Reward ID

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
user_id int Unique ID of the account owner

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.

post /v1/accounts

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
user_id int Unique ID of the user – optional, default is the ID of the authenticated user

News

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

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_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 If true, news is only visible to the project supporters
resource_uri string URL of the news resource
status string Status of the news, can be onlineor waiting
title i18n object Title of the news

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 If true, news will be visible only to the project 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 If true, news will be visible only to the project 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 a 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

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

Comment

Users may post comments on projects and news.

Comment resource

Field Type Description
comment string Body of the comment
id int Unique ID of the tag
submit_date string Date of the comment submission, with RFC 3339 format
submit_date_formatted string Relative date of the comment submission
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

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

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 the comment author.

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

List project comments

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

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

List news comments

Retrieves all the comments that belong to the news resource with the given ID.

get /v1/news/:id/comments
Parameter Description
:id News 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

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 Order is processing
awaiting-confirmation User is filling payment information
payment-completed Order is completed
cancelled User has cancelled order during the campaign
payment-done Campaign has succeeded, funds have been transfered to project owner
payment-invalid PSP needs more info to transfer payment to project owner
payment-reimbursed Campaign has failed, contributor 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
items array of order item resources Order items
note string Free field that the contributor 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 methods used for the order, can be check, creditcard, paypal, directdebit, maestro, ideal, saving, bankwire
payment_url string URL that the contributor must visit to fill payment information
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
status string Status of the order, can be processing, awaiting-confirmation, payment-completed, cancelled, payment-done, payment-invalid, payment-reimbursed, error
user user resource Author of the order

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

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. The authenticated user is_completed field must be set to true.

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

Payload for a project of type project

The contributor has two choice:

  1. Set the order amount to a value greater than or equal to the project lowest contribution amount.
  2. Select one project reward and optionally set the order amount to a value greater than or equal to the reward price.
Field Type Description
amount int Order amount – optional, must be greater than or equal to the selected reward price if reward_id is present, or must be greater than or equal to the project lowest contribution amount otherwise
billing_address_id string Billing address ID – optional
country string Country – required if the selected reward has shippings
payment_method string Payment method – required, creditcard, maestro or directdebit
reward_id int Unique ID of the reward – optional, must be a project reward
return_url string URL at which the contributor will be redirected after payment – required
shipping_address_id string Shipping address ID – optional

Payload for a project of type presale

The contributor must select at least one or more rewards.

Field Type Description
billing_address_id string Billing address ID – optional
country string Country – required if one of the selected reward has shippings
rewards array of reward items Selected rewards – required
payment_method string Payment method – required, creditcard, maestro or directdebit
return_url string Return URL, user will be redirected to this URL after payment – required
shipping_address_id string Shipping address ID – optional

Reward items

Field Type Description
id int Unique ID of the reward – optional, 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
billing_address_id int Billing address ID – optional, the address must belong to the order author
note string A note from the contributor to the project owner about this order – optional
shipping_address_id int Shipping address ID – optional, the address must belong to the order author

Cancel an order

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

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
status Order status

List project orders

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

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

Contributors may be required to create addresses resources 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
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

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 – optional, max 255 characters
address2 string Second line of the address – optional, max 255 characters
city string City – optional, max 140 characters
country string Country – optional, 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
postal_code string Postal code – optional, max 140 characters
state string State – optional, max 255 characters
type string Type – optional, must be personal, business or association, defaults to personal

Update an address

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

The country can not be updated if the address is the shipping address of an order with shippings.

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
entity_name string Entity name – max 250 characters
first_name string First name – max 30 characters
last_name string Last name – max 30 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.

An address cannot be deleted if:

  • it is the billing or shipping address of an order with shippings
  • it belongs to an account
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

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

For a proposal to go from status pending to new, the proposal must not be anonymous and the following fields must be completed:

  • name
  • description
  • rewards
  • country
  • currency
  • lang
  • nb_products_min if the type is presale
  • goal if the type is project

Proposal resource

Field Type Description
address string Address of the proposal author
answer string Answer of the moderation team
category category resource Category, null if the proposal has no category
category_id int Unique ID of the category, null if the proposal has no category
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 null, as soon as possible, in the month, in one to three months or 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
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 author, can be null, personal, business or association
manager user resource Manager assigned to the proposal, null if the proposal is unassigned
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 author
project project resource Project created from the proposal, null if the proposal has not been validated
references string References of the proposal
resource_uri string URL of the proposal resource
rewards string Description of the rewards of the proposal
status string Current status of the proposal, can be pending, new, valid, invalid, waiting or 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 Author of the proposal, can be null if the proposal is anonymous

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
category_id int Unique ID of the category – optional
country string User 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 – required if type is project
lang string Language – optional
last_name string User last name – optional, max 30 characters
links References – optional
name string Proposal name – required, 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 – required if type is presale
phone_number string Phone of the proposal user – optional
rewards string Description of the rewards – optional
structure string Structure – optional, max 150 characters
type int Project type – required, 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
category_id int Unique ID of the category
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 proposal references

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

Staff stuff

The following endpoints are only accessible to staff users.

List proposals

List all proposals. By default, this endpoint list all proposals with status new.

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.

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

Payload

Field Type Description
answer string Answer about proposal status change

Refuse Proposal

Refuses the proposal with the given ID. It changes the proposal status to invalid.

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

Payload

Field Type Description
answer string Answer about proposal status change

Suspend Proposal

Suspends the proposal with the given ID. It changes the proposal status to waiting.

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

Payload

Field Type Description
answer string Answer about proposal status change

Partnership

Partnership resource

Field Type Description
id int Unique ID of the partnership
is_default int If true, the partner is the default one for the project
is_support int
partner partner resource Partner
presale 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 partner users.

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 the partner users.

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

Payload

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

Delete a partnership

Deletes the partnership with the given ID. This endpoint has the same limitations as the create-partnership endpoint.

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

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
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.paid Occurs when an order is transferred to a project owner 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

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
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

Field Type Description
body string Body of the message – required
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

Field Type Description
body string Body of the message – required

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

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.

About this documentation

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

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