Summary

The donate.ly API is based around REST. It uses standard HTTP authentication. JSON is returned in all responses from the API, including errors.

We've tried to make it as easy to use as possible, but if you have any feedback please let us know.

API Endpoints
Before you begin

The first group of API routes are from the perspective of the donor. The /admin routes are from the perspective of the administrator of an account.

Requests will require your api token passed in the authentication header (basic http auth). You can find this api token in your personal profile page.

Tokens

To start using the donate.ly API, you will first need your token. Every Donately user has a token that allows them access to their own personal data, and the data for accounts that they have admin priviledges to. You can find your token by signing into Donately and visiting your personal profile page

Authentication

Pass your token using Basic Authentication over HTTPS

cURL Example
curl -X GET https://www.dntly.com/api/v1/accounts.json \
-u <API TOKEN>:

Accounts

GET /accounts

Retrieves list of the accounts you are connected to.

Definition
GET https://www.dntly.com/api/v1/accounts.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/accounts.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  accounts: [
    {
      id:                1,
      unique_identifier: act_wr7ncbgis87h,
      title:             "Fifty and Fifty",
      subdomain:         "fiftyandfifty"
    },
    {...},
    {...}
  ]
}
GET /accounts/{ID}

Shows info about an account.

Definition
GET https://www.dntly.com/api/v1/accounts/{ID}.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/accounts/1.json \
-u <API TOKEN>: \
Example Response
{
  success: true,
  account: {
    id: 1,
    unique_identifier: act_wr7ncbgis87h,
    title: "Fifty and Fifty",
    subdomain: "fiftyandfifty"
  }
}
POST /accounts/{ID}/donate_without_auth

Makes a donation without requiring token header authorization.

Definition
POST https://www.dntly.com/api/v1/accounts/{ID}/donate_without_auth.json
Required Parameters
  • email
  • amount_in_cents
  • card (accepts a stripe_token only)
Optional Parameters
  • recurring (boolean of true or false)
  • comment
  • on_behalf_of (string representation of someone's name)
  • anonymous (boolean of true or false)
  • campaign_id
  • fundraiser_id (associated campaign_id is also required if setting fundraiser_id)
  • first_name
  • last_name
  • phone_number
  • street_address
  • street_address_2
  • city
  • state
  • zip_code
  • country
  • interested_in_fundraising (boolean of true or false)
  • dump (arbitrary string field for dumping your own values into - possibly you might use this for your own custom tracking)
  • dont_send_receipt_email (send your own custom one - boolean of true or false)
Example Request
curl -X POST https://www.dntly.com/api/v1/accounts/1/donate_without_auth.json \
-d "email=test@example.com" \
-d "amount_in_cents=1000" \
-d "card=tok_7OT6LL2X6frNiO"
Example Response
{
  success: true,
  donation: {
    id: 1,
    unique_identifier: dnt_wr7ncbgis87h,
    amount_in_cents: 1000
  }
}

People

POST /people/update_me

Updates your person.

Definition
POST https://www.dntly.com/api/v1/people/update_me.json
Required Paramaeters

none

Optional Parameters
  • email
  • first_name
  • last_name
  • phone_number
  • street_address
  • street_address_2
  • city
  • state
  • zip_code
  • country
Example Request
curl -X POST https://www.dntly.com/api/v1/people/update_me.json \
-u <API TOKEN>: \
-d "email=different@email.com"
Example Response
{
  success: true,
  person: {
    id:                 1,
    unique_identifier:  per_wr7ncbgis87h,
    email:              "different@email.com,
    first_name:         null,
    last_name:          null,
    phone_number:       null,
    street_address:     null,
    street_address_2:   null,
    city:               null,
    state:              null,
    zip_code:           null,
    country:            null,
    account_ids:        [1]
  }
}
POST /people/forgot_password

Sends an email to the person with password reset instructions.

Definition
POST https://www.dntly.com/api/v1/people/forgot_password.json
Required Parameters
  • email
Example Request
curl -X POST https://www.dntly.com/api/v1/people/forgot_password.json \
-d "email=test@example.com"
Example Response
{
  success: true,
  message: "Email sent to test@example.com"
}
POST /people/reset_forgotten_password

Resets forgotten password.

Definition
POST https://www.dntly.com/api/v1/people/reset_forgotten_password.json
Required Parameters
  • email
  • reset_password_token
  • new_password
Example Request
curl -X POST https://www.dntly.com/api/v1/people/forgot_password.json \
-d "email=test@example.com" \
-d "reset_pasword_token={RESET_PASSWORD_TOKEN}" \
-d "new_password=password"
Example Response
{
  success: true,
  person: {
    id:                 1,
    unique_identifier:  per_wr7ncbgis87h,
    email:              "test@example.com,
    first_name:         null,
    last_name:          null,
    phone_number:       null,
    street_address:     null,
    street_address_2:   null,
    city:               null,
    state:              null,
    zip_code:           null,
    country:            null,
    account_ids:        [1]
  }
}
POST /people/join_account

Joins your person to an account.

Definition
POST https://www.dntly.com/api/v1/people/join_account.json
Required Parameters
  • account_id
Example Request
curl -X POST https://www.dntly.com/api/v1/people/join_account.json \
-u <API TOKEN>: \
-d "account_id=77"
Example Response
{
  success: true,
  person: {
    id:                 1,
    unique_identifier:  per_wr7ncbgis87h,
    email:              "test@example.com,
    first_name:         null,
    last_name:          null,
    phone_number:       null,
    street_address:     null,
    street_address_2:   null,
    city:               null,
    state:              null,
    zip_code:           null,
    country:            null,
    account_ids:        [1,7]
  }
}
GET /people/show

Shows your person.

Definition
GET https://www.dntly.com/api/v1/people/show.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/people/show.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  person: {
    id:                 1,
    unique_identifier:  per_wr7ncbgis87h,
    email:              "test@example.com,
    first_name:         null,
    last_name:          null,
    phone_number:       null,
    street_address:     null,
    street_address_2:   null,
    city:               null,
    state:              null,
    zip_code:           null,
    country:            null,
    account_ids:        [1,7],
    donation_amount_in_cents:     0,
    donation_amount:              0,
    donation_amount_formatted:    "$0.00",
    fundraised_amount_in_cents:   0,
    fundraised_amount:            0,
    fundraised_amount_formatted: "$0.00"
  }
}

Donations

GET /donations

Retrieves list of the existing donations for your person.

Definition
GET https://www.dntly.com/api/v1/donations.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/donations.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  donations: [
    {
      id: 1,
      unique_identifier: dnt_wr7ncbgis87h,
      account_id: 1,
      campaign_id: null,
      fundraiser_id: null,
      account_title: "Mercy Ships",
      campaign_title: null,
      fundraiser_title: null,
      amount_in_cents: 10000,
      amount: 100,
      amount_formatted: "$100.00",
      created: 1345481845000
    },
    {...},
    {...}
  ]
}
POST /donations/{ID}/update

Updates the donation.

Definition
POST https://www.dntly.com/api/v1/donations/{ID}/update.json
Required Parameters

none

Optional Parameters
  • comment
Example Request
curl -X GET https://www.dntly.com/api/v1/donations/1/update.json \
-u <API TOKEN>: \
-d "comment='This is a comment'"
Example Response
{
  success: true,
  donation: {
    id: 1,
    unique_identifier: dnt_wr7ncbgis87h,
    parent_id: null,
    account_id: 1,
    campaign_id: null,
    fundraiser_id: null,
    account_title: "Mercy Ships",
    campaign_title: null,
    fundraiser_title: null,
    amount_in_cents: 10000,
    amount: 100,
    amount_formatted: "$100.00",
    comment: "This is a comment",
    created: 1345481845000
  }
}

Fundraisers

GET /fundraisers

Retrieves list of fundraisers for your person.

Definition
GET https://www.dntly.com/api/v1/fundraisers.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/fundraisers.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  fundraisers: [
    {
      id:                       1,
      unique_identifier:        fun_wr7ncbgis87h,
      title:                    "A Fundraiser",
      account_title:            "Fifty and Fifty",
      permalink:                "a-fundraiser",
      description:              "",
      goal_in_cents:            10000,
      goal:                     100,
      goal_formatted:           "$100.00",
      amount_raised_in_cents:   1000,
      amount_raised:            10,
      amount_raised_formatted:  "$10.00",
      campaign_id:              1,
      account_id:               1,
      person_id:                1,
      public_url:               {URL},
      iframe_url:               {URL},
      photo {
        original:     {URL},
        medium:       {URL},
        average:      {URL},
        small:        {URL},
        thumb:        {URL},
        icon:         {URL}
      }
    },
    {...},
    {...}
  ]
}
POST /fundraisers

Create a fundraiser.

Definition
POST https://www.dntly.com/api/v1/fundraisers.json
Required Parameters
  • title
  • description
  • goal_in_cents
  • campaign_id
Optional Parameters
  • photo
Example Request
curl -X POST https://www.dntly.com/api/v1/fundraisers.json \
-u <API TOKEN>: \
-d "title='A Fundraiser'" \
-d "description='Description of fundraiser'" \
-d "goal_in_cents=10000" \
-d "campaign_id=1"
-F file=@/some/file/on/your/local/disk
Example Response
{
  success: true,
  fundraiser: {
    id:                       1,
    unique_identifier:        fun_wr7ncbgis87h,
    title:                    "A Fundraiser",
    permalink:                "a-fundraiser",
    description:              "",
    goal_in_cents:            10000,
    goal:                     100,
    goal_formatted:           "$100.00",
    amount_raised_in_cents:   1000,
    amount_raised:            10,
    amount_raised_formatted:  "$10.00",
    campaign_id:              1,
    account_id:               1,
    person_id:                1,
    public_url:               {URL},
    iframe_url:               {URL},
    photo {
      original:     {URL},
      medium:       {URL},
      average:      {URL},
      small:        {URL},
      thumb:        {URL},
      icon:         {URL}
    }
  ]
}
GET /fundraisers/{ID}

Retrieves a fundraiser for your person.

Definition
GET https://www.dntly.com/api/v1/fundraisers/{ID}.json
Required Parameters

none

Example Request
curl -X GET https://www.dntly.com/api/v1/fundraisers/{ID}.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  fundraiser: {
    id:                       1,
    unique_identifier:        fun_wr7ncbgis87h,
    title:                    "A Fundraiser",
    permalink:                "a-fundraiser",
    description:              "",
    goal_in_cents:            10000,
    goal:                     100,
    goal_formatted:           "$100.00",
    amount_raised_in_cents:   1000,
    amount_raised:            10,
    amount_raised_formatted:  "$10.00",
    campaign_id:              1,
    account_id:               1,
    person_id:                1,
    public_url:               {URL},
    iframe_url:               {URL},
    photo {
      original:     {URL},
      medium:       {URL},
      average:      {URL},
      small:        {URL},
      thumb:        {URL},
      icon:         {URL}
    }
  ]
}
POST /fundraisers/{ID}/update

Updates a fundraiser.

Definition
POST https://www.dntly.com/api/v1/fundraisers/{ID}.json
Required Parameters
  • title
  • description
  • goal_in_cents
  • campaign_id
Optional Parameters
  • photo
Example Request
curl -X POST https://www.dntly.com/api/v1/fundraisers/{ID}.json \
-u <API TOKEN>: \
-d "title='A Fundraiser'" \
-d "description='Description of fundraiser'" \
-d "goal_in_cents=10000" \
-d "campaign_id=1"
-F file=@/some/file/on/your/local/disk
Example Response
{
  success: true,
  fundraiser: {
    id:                       1,
    unique_identifier:        fun_wr7ncbgis87h,
    title:                    "A Fundraiser",
    permalink:                "a-fundraiser",
    description:              "",
    goal_in_cents:            10000,
    goal:                     100,
    goal_formatted:           "$100.00",
    amount_raised_in_cents:   1000,
    amount_raised:            10,
    amount_raised_formatted:  "$10.00",
    campaign_id:              1,
    account_id:               1,
    person_id:                1,
    public_url:               {URL},
    iframe_url:               {URL},
    photo {
      original:     {URL},
      medium:       {URL},
      average:      {URL},
      small:        {URL},
      thumb:        {URL},
      icon:         {URL}
    }
  ]
}

Admin/Account

GET /admin/account/show

Shows your admin account.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/show.json
Required Parameters

none

Example Request
curl -X GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/show.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  account: {
    id:                         1,
    unique_identifier:          act_wr7ncbgis87h,
    title:                      "5050",
    subdomain:                  "fiftyandfifty",
    mail_reply_to:              null,
    home_link_url:              null,
    allow_anonymous_donations:  false,
    allow_on_behalf_of:         false,
    can_process_payments:       true,
    logo: {
      ...
    },
    header: {
      ...
    }
  }
}
POST /admin/account/update

Updates your account.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/update.json
Required Parameters

none

Optional Parameters
  • title
  • subdomain
  • description
  • mail_reply_to
  • home_link_url
  • google_analytics_id
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/account/update.json \
-u <API TOKEN>: \
-d "title=5050"
Example Response
{
  success: true,
  account: {
    id:                       1,
    unique_identifier:        act_wr7ncbgis87h,
    title:                    "5050",
    subdomain:                "fiftyandfifty"
  }
}
POST /admin/account/update_credit_card

Updates your account.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/update_credit_card.json
Required Parameters
  • card (accepts a stripe_token only)
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/account/update_credit_card.json \
-u <API TOKEN>: \
-d "card=tok_7OT6LL2X6frNiO"
Example Response
{
  success: true,
  account: {
    id:                       1,
    unique_identifier:        act_wr7ncbgis87h,
    title:                    "Fifty and Fifty",
    subdomain:                "fiftyandfifty",
    stripe_secret_key:        {KEY},
    stripe_publishable_key:   {KEY},
    referrer:                 null,
    cc_type:                  "visa",
    cc_last4:                 "4242",
    cc_exp_month:             "12",
    cc_exp_year:              "2014"
  }
}
GET /admin/account/current_usage

Shows your current usage statistics.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/current_usage.json
Required Parameters

none

Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/account/current_usage.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  fees_in_cents:           20000,
  fees_formatted           "$200",
  donation_fees_in_cents   10000,
  donation_fees_formatted  "$100",
  person_fees_in_cents     10000,
  person_fees_formatted    "$100"
  donations: [
    {
      id:               1,
      unique_identifier:dnt_wr7ncbgis87h,
      name:             "John Doe",
      amount_in_cents:  100,
      amount_formatted: "$1",
      fee_in_cents:     2,
      fee_formatted:    "$0.02"
    },
    {...},
    {...}
  ]

  people: [
    {
      id:                1,
      unique_identifier: per_wr7ncbgis87h,
      name:              "John Doe",
      fee_in_cents:      50,
      fee_formatted:     "$0.50"
    },
    {...},
    {...}
  ]
}
GET /admin/account/stats

Shows account statistics.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/account/stats.json
Required Parameters

none

Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/account/stats.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  amount_raised_in_cents:     10000,
  amount_raised:              100,
  amount_raised_formatted:    "$100.00",
  donations_count:            5,
  one_time_amount_raised_in_cents:     5000,
  one_time_amount_raised:              50,
  one_time_amount_raised_formatted:    "$50.00",
  recurring_amount_raised_in_cents:     5000,
  recurring_amount_raised:              50,
  recurring_amount_raised_formatted:    "$50.00",
}

Admin/Campaigns

GET /admin/campaigns

Retrieves list of the existing campaigns on the subdomain.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/campaigns.json
Required Parameters

none

Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/campaigns.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  campaigns: [
    {
      id:                       1,
      unique_identifier:        cmp_wr7ncbgis87h,
      title:                    "Campaign Title",
      goal_in_cents:            100000,
      created:                  1345481845000,
      state:                    "published",
      ...
    },
    {...},
    {...}
  ]
}
GET /admin/campaigns/{ID}

Retrieves a campaign.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/campaigns/{ID}.json
Required Parameters

none

Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/campaigns/{ID}.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  campaign: {
    id:                       1,
    title:                    "New Title",
    description:              null,
    goal_in_cents:            50000,
    amount_raised_in_cents:   10000,
    created:                  1345481845000,
    state:                    "published"
    ...
  }
}
POST /admin/campaigns

Creates a campaign.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/campaigns.json
Required Parameters
  • title
  • goal_in_cents
Optional Parameters
  • description
  • content
  • allow_fundraisers
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/campaigns.json \
-u <API TOKEN>: \
-d "title='Campaign Title'" \
-d "goal_in_cents=50000"
Example Response
{
  success: true,
  campaign: {
    id:                       1,
    unique_identifier:        cmp_wr7ncbgis87h,
    title:                    "New Title",
    description:              null,
    goal_in_cents:            50000,
    amount_raised_in_cents:   10000,
    allow_fundraisers:        false,
    created:                  1345481845000,
  }
}
POST /admin/campaigns/{ID}/update

Updates a campaign.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/campaigns/{ID}/update.json
Required Parameters

none

Optional Parameters
  • title
  • goal_in_cents
  • description
  • content
  • allow_fundraisers
  • state (allowed string values: published, archived)
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/campaigns/1/update.json \
-u <API TOKEN>: \
-d "title='New Title'"
Example Response
{
  success: true,
  campaign: {
    id:                       1,
    unique_identifier:        cmp_wr7ncbgis87h,
    title:                    "New Title",
    description:              null,
    goal_in_cents:            50000,
    amount_raised_in_cents:   10000,
    allow_fundraisers:        false,
    created:                  1345481845000,
    state:                    'published'
  }
}

Admin/People

GET /admin/people

Retrieves list of all people in account.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/people.json
Required Parameters

none

Optional Parameters
  • count (default is 10. A limit on the number of people to be returned. Count can range between 1 and 100 people.)
  • offset (default is 0. An offset into your people array. The API will return the requested number of people starting at that offset.)
  • order (options, i.e. ?order=donation_amount_in_cents)
  • include_referrers (boolean, true or false, i.e. ?include_referrers=true)
  • search (string, search by first_name, last_name, or email)
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/people.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  total_count: 51,
  count: 10,
  offset: 0,
  people: [
    {
      id:                             1,
      unique_identifier:              per_wr7ncbgis87h,
      email:                          "you@email.com",
      first_name:                     "Scott",
      last_name:                      "Motte",
      donation_amount_in_cents:       50000,
      donation_amount:                500,
      donation_amount_formatted:      "$500.00",
      updated:                        1345481845000
    },
    {...},
    {...}
  ]
}
GET /admin/people/{ID}

Retrieves a person in the account by id.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/people/{ID}.json
Required Parameters

none

Optional Parameters
  • donation_status (any, processed, refunded ?donation_status=processed)
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/people/1.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  person: {
    id:                             1,
    unique_identifier:              per_wr7ncbgis87h,
    email:                          "you@email.com",
    first_name:                     "Scott",
    last_name:                      "Motte",
    street_address:                 "629 J Street",
    street_address_2:               "Unit 207",
    city:                           "San Diego",
    state:                          "CA",
    zip_code:                       "92101",
    phone_number:                   "610-555-1234",
    donation_amount_in_cents:       50000,
    donation_amount:                500,
    donation_amount_formatted:      "$500.00",
    fundraised_amount_in_cents:     1000,
    fundraised_amount:              10,
    fundraised_amount_formatted:    "$10.00",
    status:                         "Donor",
    updated:                        1345481845000
    donations: [
      {...},
      {...}
    ]
    fundraisers: [
      {...},
      {...}
    ]
  }
}
GET /admin/person/by_email

Retrieves a person in the account by their email address.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/person/by_email.json
Required Parameters
  • email
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/person/by_email.json \
-u <API TOKEN>: \
-d "email='person@example.com'"
Example Response
{
  success: true,
  person: {
    id:                             1,
    unique_identifier:              per_wr7ncbgis87h,
    email:                          "you@email.com",
    first_name:                     "Scott",
    last_name:                      "Motte",
    street_address:                 "629 J Street",
    street_address_2:               "Unit 207",
    city:                           "San Diego",
    state:                          "CA",
    zip_code:                       "92101",
    phone_number:                   "610-555-1234",
    donation_amount_in_cents:       50000,
    donation_amount:                500,
    donation_amount_formatted:      "$500.00",
    fundraised_amount_in_cents:     1000,
    fundraised_amount:              10,
    fundraised_amount_formatted:    "$10.00",
    status:                         "Donor",
    updated:                        1345481845000
    donations: [
      {...},
      {...}
    ]
    fundraisers: [
      {...},
      {...}
    ]
  }
}
POST /admin/people/{ID}/update

Updates a person.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/people/{ID}/update.json
Required Parameters

none

Optional Parameters
  • email
  • first_name
  • last_name
  • street_address
  • street_address_2
  • city
  • state
  • zip_code
  • phone_number
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/people/1/update.json \
-u <API TOKEN>: \
-d "first_name='NewName'"
Example Response
{
  success: true,
  person: {
    id:                             1,
    unique_identifier:              per_wr7ncbgis87h,
    email:                          "you@email.com",
    first_name:                     "Scott",
    last_name:                      "Motte",
    street_address:                 "629 J Street",
    street_address_2:               "Unit 207",
    city:                           "San Diego",
    state:                          "CA",
    zip_code:                       "92101",
    phone_number:                   "610-555-1234",
    donation_amount_in_cents:       50000,
    donation_amount:                500,
    donation_amount_formatted:      "$500.00",
    fundraised_amount_in_cents:     1000,
    fundraised_amount:              10,
    fundraised_amount_formatted:    "$10.00",
    status:                         "Donor",
    updated:                        1345481845000
    donations: [
      {...},
      {...}
    ]
    fundraisers: [
      {...},
      {...}
    ]
  }
}

Admin/Donations

The Donation Object
  • id (The internal id of this Donation) [type: integer]
  • unique_identifier (The external id of this Donation) [type: alphanumeric prefixed with dnt_]
  • amount_in_cents (The donation amount in cents with no decimal) [type: integer]
  • amount (The donation amount in decimal form) [type: float]
  • amount_formatted (The donation amount formatted in decimal form) [type: string]
  • person_id (The internal id of the Person/Donor associated with this Donation) [type: integer]
  • person_unique_identifier (The external id of the Person/Donor associated with this Donation) [type: alphanumeric prefixed with per_]
  • email (The unique email address associated with the Person/Donor for this Donation) [type: string]
  • first_name (The optional first name associated with the Person/Donor for this Donation) [type: string]
  • last_name (The optional last name associated with the Person/Donor for this Donation) [type: string]
  • full_name_or_email (The full name or email associated with the Person/Donor for this Donation. This can be used for communications where full name might not exist) [type: string]
  • street_address (The optional address associated with the Person/Donor for this Donation) [type: string]
  • street_address_2 (The optional extended address associated with the Person/Donor for this Donation) [type: string]
  • city (The optional city associated with the Person/Donor for this Donation) [type: string]
  • state (The optional state associated with the Person/Donor for this Donation) [type: string]
  • zip_code (The optional postal code associated with the Person/Donor for this Donation) [type: string
  • country (The optional country associated with the Person/Donor for this Donation) [type: string
  • phone_number (The optional phone number associated with the Person/Donor for this Donation) [type: string
  • parent_id (For recurring donations only, this is the internal id of the first recurring donation for the associated subscription. Nil for one-time donations and for the first recurring donation in a subscription) [type: integer]
  • parent_unique_identifier (For recurring donations only, this is the external id of the first recurring donation for the associated subscription. Nil for one-time donations and for the first recurring donation in a subscription) [type: alphanumeric prefixed with dnt_]
  • account_id (The internal id of the associated account) [type: integer]
  • account_unique_identifier (The external id of the associated account) [type: alphanumeric prefixed with act_]
  • campaign_id (The internal id of the associated campaign, if exists) [type: integer]
  • campaign_unique_identifier (The external id of the associated campaign, if exists) [type: alphanumeric prefixed with cmp_]
  • fundraiser_id (The internal id of the associated fundraiser, if exists) [type: integer]
  • fundraiser_unique_identifier (The external id of the associated fundraiser, if exists) [type: alphanumeric prefixed with fun_]
  • fundraiser_email (The unique email address associated with the Person/Donor of the associated fundraiser, if exists) [type: string]
  • fundraiser_first_name (The optional first name associated with the Person/Donor of the associated fundraiser, if exists) [type: string]
  • fundraiser_last_name (The optional last name associated with the Person/Donor of the associated fundraiser, if exists) (The optional first name associated with the Person/Donor of the associated fundraiser, if exists) [type: string]
  • recurring (True for recurring donations, nil/false for one-time donations) [type: boolean]
  • subscription_sid (The internal id of the associated subscription, if exists) [type: integer]
  • subscription_state (The state of the associated subscription, if exists) [type: string] {possible values: "suspended", "canceled", "active", "failed_one", "failed_two", "failed_three", "failed_four"}
  • subscription_unique_identifier (The external id of the associated subscription, if exists) [type: alphanumeric prefixed with sub_]
  • anonymous (True for anonymous donations) [type: boolean]
  • transaction_id (The Stripe transaction id) [type: string]
  • subscription_id (Deprecated Authorize.net field)
  • subscription_paynum (Deprecated Authorize.net field)
  • cc_type (The type of credit card used for this donation, if exists) [type: string] {possible values: "American Express", "MasterCard", "Visa", "Discover", "Unknown", "JCB", "Diners Club"}
  • cc_last4 (The last 4 digits of the credit card used for this donation, if exists) [type: string]
  • cc_exp_month (The 2 digit expiration month of the credit card used for this donation, if exists) [type: string]
  • cc_exp_year (The 4 digit expiration year of the credit card used for this donation, if exists) [type: string]
  • donation_type (The type of donation) [type: string] {possible values: "cc", "cash/check", "ach"}
  • refundable (True for donations not-yet refunded) [type: boolean]
  • status (The status of this donation) [type: string] {possible values: "processed", "canceled", "voided", "refunded"}
  • donation_date (The date & time this donation was created. This can be edited.) [type: datetime]
  • on_behalf_of (The optional on behalf of information for this donation) [type: string]
  • comment (The optional comment for this donation) [type: text]
  • processor (The Merchant Processor for this donation, currently only 'S' for 'Stripe') [type: string]
  • dump (The optional tracking dump for this donation) [type: text]
  • refunded_at (The date & time this donation was refunded, if exists) [type: datetime]
  • created_at (The date & time this donation was created. This cannot be edited.) [type: datetime]
  • created (The timestamp in milliseconds this donation was created) [type: integer]
  • notes (The optional internal admin notes for this donation) [type: text]
  • livemode (True for Donations using the Live Stripe keys. testmode Donations can be deleted) [type: boolean]
  • currency (The currency for this Donation) [type: string] {possible values: "usd"}
  • meta_data (The optional meta data for this donation) [type: json text]
GET /admin/donations

Retrieves list of the existing donations paid to your account.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/donations.json
Required Parameters

none

Optional Parameters
  • count (default is 10. A limit on the number of donations to be returned. Count can range between 1 and 100 donations.)
  • offset (default is 0. An offset into your donations array. The API will return the requested number of donations starting at that offset.)
  • recurring_only (boolean, true or false, i.e. ?recurring_only=true)
  • campaign_id (integer, i.e. ?campaign_id=1234)
  • fundraiser_id (integer, i.e. ?fundraiser_id=1234)
  • amount_in_cents (integer in cents ?amount_in_cents=100)
  • amount_in_cents[gt] (integer in cents ?amount_in_cents[gt]=100)
  • amount_in_cents[lt] (integer in cents ?amount_in_cents[lt]=100)
  • created (unix time in milliseconds ?created=1347419072000)
  • created[gt] (unix time in milliseconds ?created[gt]=1347419072000)
  • created[lt] (unix time in milliseconds ?created[lt]=1347419072000)
  • order (asc or desc ?order=asc)
  • order_by (can be amount_in_cents. Combine with order to sort by biggest givers and lesser givers. ?order_by=amount_in_cents)
  • status (any, processed, refunded ?status=processed)
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/donations.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  total_count: 51,
  count: 10,
  offset: 0,
  donations: [
    {
      id:                              1,
      unique_identifier:               dnt_wr7ncbgis87h,
      amount_in_cents:                 10000
      amount:                          100
      amount_formatted:                "$100"
      person_id:                       1,
      email:                           "someone@email.com",
      first_name:                      "John",
      last_name:                       "Smith",
      street_address:                  "123 Main St.",
      street_address_2:                "Suite 10",
      city:                            "San Diego",
      state:                           "CA",
      zip_code:                        "92101",
      country:                         "US",
      phone_number:                    "555-555-5555",
      parent_id:                       null,
      account_id:                      1,
      campaign_id:                     null,
      fundraiser_id:                   null,
      recurring:                       false,
      subscription_state:              null,
      subscription_unique_identifier:  null,
      anonymous:                       false,
      transaction_id:                  {KEY},
      subscription_id:                 null,
      subscription_paynum:             null,
      cc_type:                         "Visa",
      cc_last4:                        "4242",
      cc_exp_month:                    "8",
      cc_exp_year:                     "2014",
      donation_type:                   "cc",
      status:                          "processed",
      donation_date:                   null,
      on_behalf_of:                    null,
      processor:                       "S",
      dump:                            "dump arbitrary string values into here",
      created:                         1345481845000
    },
    {...},
    {...}
  ]
}
POST /admin/donations/{ID}/update

Updates a donation.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/donations/{ID}/update.json
Required Parameters

none

Optional Parameters
  • campaign_id
  • fundraiser_id
  • anonymous
  • recurring
  • on_behalf_of
  • comment
  • notes
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/donations/1/update.json \
-u <API TOKEN>: \
-d "campaign_id='1099'"
Example Response
{
  success: true,
  message: The donation has been updated successfully.,
  donation: [
    {
      id :                             1,
      unique_identifier:               dnt_wr7ncbgis87h,
      amount_in_cents:                 10000
      amount:                          100
      amount_formatted:                "$100"
      person_id:                       1,
      email:                           "someone@email.com",
      first_name:                      "John",
      last_name:                       "Smith",
      street_address:                  "123 Main St.",
      street_address_2:                "Suite 10",
      city:                            "San Diego",
      state:                           "CA",
      zip_code:                        "92101",
      country:                         "US",
      phone_number:                    "555-555-5555",
      parent_id:                       null,
      account_id:                      1,
      campaign_id:                     1099,
      fundraiser_id:                   null,
      recurring:                       false,
      subscription_state:              null,
      subscription_unique_identifier:  null,
      anonymous:                       false,
      transaction_id:                  {KEY},
      subscription_id:                 null,
      subscription_paynum:             null,
      cc_type:                         "Visa",
      cc_last4:                        "4242",
      cc_exp_month:                    "8",
      cc_exp_year:                     "2014",
      donation_type:                   "cc",
      status:                          "processed",
      donation_date:            null,
      on_behalf_of:                    null,
      processor:                       "S",
      dump:                            "dump arbitrary string values into here",
      created:                         1345481845000
      notes:                            "admin notes",
    }
  ]
}
POST /admin/donations/cash

Makes a cash/check donation.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/donations/cash
Required Parameters
  • amount_in_cents
Optional Parameters
  • email (not required, but recommended. Donately will create a unique temporary email address, if missing)
  • recurring (boolean of true or false)
  • comment
  • on_behalf_of (string representation of someone's name)
  • anonymous (boolean of true or false)
  • campaign_id
  • fundraiser_id (associated campaign_id is also required if setting fundraiser_id)
  • first_name
  • last_name
  • phone_number
  • street_address
  • street_address_2
  • city
  • state
  • zip_code
  • country
  • interested_in_fundraising (boolean of true or false)
  • dump (arbitrary string field for dumping your own values into - possibly you might use this for your own custom tracking)
  • dont_send_receipt_email (send your own custom one - boolean of true or false)
  • donation_date (YYYY-MM-DD format - for recording offline donations not placed today)
  • notes
Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/donations/cash.json \
-u <API TOKEN>: \
-d "email=test@example.com" \
-d "amount_in_cents=1000"
Example Response
{
  success: true,
  donation: {
    id:                 1,
    unique_identifier:  dnt_wr7ncbgis87h,
    amount_in_cents:    1000
  }
}
POST /admin/donations/{ID}/refund

Refunds a donation.

Definition
POST https://{SUBDOMAIN}.dntly.com/api/v1/admin/donations/1/refund.json
Required Parameters

none

Example Request
curl -X POST https://fiftyandfifty.dntly.com/api/v1/admin/donations/1/refund.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  refund: {
    id:                   1,
    unique_identifier:    ref_wr7ncbgis87h,
    amount_in_cents:      1000,
    amount:               1000,
    ...
  }
}

Admin/Subscriptions

The Subscription Object
  • id (The internal id of this Subscription) [type: integer]
  • unique_identifier (The external id of this Subscription) [type: alphanumeric prefixed with sub_]
  • amount (The Subscription amount in decimal form) [type: float]
  • amount_in_cents (The Subscription amount in cents with no decimal) [type: integer]
  • account_unique_identifier (The external id of the associated account) [type: alphanumeric prefixed with act_]
  • campaign_id (The internal id of the associated campaign, if exists) [type: integer]
  • fundraiser_id (The internal id of the associated fundraiser, if exists) [type: integer]
  • donation_type (The type of donation) [type: string] {possible values: "cc", "cash/check", "ach"}
  • anonymous (True for anonymous donations) [type: boolean]
  • created (The timestamp this Subscription was created) [type: integer]
  • created_at (The date & time this donation was created. This cannot be edited.) [type: datetime]
  • comment (The optional comment for this Subscription) [type: text]
  • donation_parent_id (The internal id of the first recurring donation for this Subscription) [type: integer]
  • donation_parent_unique_identifier (The external id of the first recurring donation for this Subscription) [type: alphanumeric prefixed with dnt_]
  • notes (The optional internal admin notes for this Subscription) [type: text]
  • on_behalf_of (The optional on behalf of information for this Subscription) [type: string]
  • processor (The Merchant Processor for this Subscription, currently only 'S' for 'Stripe') [type: string]
  • referrer_id (The internal id of the referrer - not used) [type: integer]
  • state (The state of the subscription) [type: string] {possible values: "suspended", "canceled", "active", "failed_one", "failed_two", "failed_three", "failed_four"}
  • updated_at (The date & time this Subscription was updated. This cannot be edited.) [type: datetime]
  • cc_type (The type of credit card used for this Subscription, if exists) [type: string] {possible values: "American Express", "MasterCard", "Visa", "Discover", "Unknown", "JCB", "Diners Club"}
  • cc_last4 (The last 4 digits of the credit card used for this Subscription, if exists) [type: string]
  • cc_exp_month (The 2 digit expiration month of the credit card used for this Subscription, if exists) [type: string]
  • cc_exp_year (The 4 digit expiration year of the credit card used for this Subscription, if exists) [type: string]
  • person_id (The internal id of the Person/Donor associated with this Subscription) [type: integer]
  • full_name_or_email (The full name or email associated with the Person/Donor for this Subscription) [type: string]
  • recurring_day_of_month (For monthly recurring donations, the month day this Subscription runs on) [type: integer]
  • recurring_start_day (The date before which this Subscription will not run) [type: date]
  • recurring_stop_day (The optional date after which this Subscription will not run) [type: date]
  • recurring_frequency (The frequency this Subscription runs, defaults to 1.month. API v1 cannot create recurring donations with frequencies other than 1.month, but you can update existing recurring donations to be any frequency) [type: string] {possible values: "1.day", "2.day", "3.day", "7.day", "14.day", "28.day", "1.month", "2.month", "3.month", "4.month", "6.month", "12.month"}
  • total_donations_amount_in_cents (The total, including refunded donations, amount in cents for this Subscription with no decimal) [type: integer]
  • total_successful_donations_amount_in_cents (The total, not including refunded donations, amount in cents for this Subscription with no decimal) [type: integer]
  • total_donations_count (The total, including refunded donations, count for this Subscription with no decimal) [type: integer]
  • total_successful_donations_count (The total, not including refunded donations, count for this Subscription with no decimal) [type: integer]
  • card_expires_in_months (The number of months until this Subscription's credit card expires) [type: float]
  • last_date_ran (The last date this Subscription was run) [type: date]
  • next_date_it_will_run (The next date this Subscription will run, taking into account the recurring_frequency, recurring_start_day & recurring_stop_day ) [type: date]
  • next_run_dates (The next 7 dates this Subscription will run, taking into account the recurring_frequency, recurring_start_day & recurring_stop_day ) [type: date array]
GET /admin/subscriptions

Retrieves list of the existing subscriptions for your account.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/subscriptions.json
Required Parameters

none

Optional Parameters
  • count (default is 10. A limit on the number of subscriptions to be returned. Count can range between 1 and 100 subscriptions.)
  • offset (default is 0. An offset into your subscriptions array. The API will return the requested number of subscriptions starting at that offset.)
  • campaign_id (integer, i.e. ?campaign_id=1234)
  • fundraiser_id (integer, i.e. ?fundraiser_id=1234)
  • amount_in_cents (integer in cents ?amount_in_cents=100)
  • created (unix time in milliseconds ?created=1347419072000)
  • created[gt] (unix time in milliseconds ?created[gt]=1347419072000)
  • created[lt] (unix time in milliseconds ?created[lt]=1347419072000)
  • order (asc or desc ?order=asc)
  • order_by (can be amount_in_cents. Combine with order to sort by biggest givers and lesser givers. ?order_by=amount_in_cents)
  • state (active, canceled, failed, empty for all states)
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/subscriptions.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  total_active: 40215.0,
  total_count: 51,
  count: 10,
  offset: 0,
  subscriptions: [
    {
      id:                              1,
      unique_identifier:               sub_wrf7nhygs0o,
      amount_in_cents:                 10000
      amount:                          100
      ...
    },
    {...},
    {...}
  ]
}
POST /subscriptions/{ID}/update

Updates the subscription.

Definition
POST https://www.dntly.com/api/v1/subscriptions/{ID}/update.json
Required Parameters

none

Optional Parameters
  • amount_in_cents
  • recurring_frequency
  • recurring_start_day
  • recurring_stop_day
  • state
  • campaign_id
  • fundraiser_id
  • anonymous
  • on_behalf_of
  • comment
  • notes
Example Request
curl -X GET https://www.dntly.com/api/v1/subscriptions/123/update.json \
-u <API TOKEN>: \
-d "recurring_frequency='14.day'"
Example Response
{
  success: true,
  subscription: {
    id: 1,
    unique_identifier: sub_wrf7nhygs0o,
    recurring_frequency: 14.day,
    ...
  }
}

Admin/Fundraiers

GET /admin/fundraisers

Retrieves list of the existing fundraisers for your account.

Definition
GET https://{SUBDOMAIN}.dntly.com/api/v1/admin/fundraisers.json
Required Parameters

none

Optional Parameters
  • count (default is 10. A limit on the number of people to be returned. Count can range between 1 and 100 people.)
  • offset (default is 0. An offset into your people array. The API will return the requested number of people starting at that offset.)
  • include_archived (boolean, true or false, i.e. ?include_archived=true) This will include archived fundraisers in the list.
Example Request
curl -X GET https://fiftyandfifty.dntly.com/api/v1/admin/fundraisers.json \
-u <API TOKEN>:
Example Response
{
  success: true,
  total_count: 51,
  count: 10,
  offset: 0,
  fundraisers: [
    {
      id:                       1,
      unique_identifier:        fun_wr7ncbgis87h,
      title:                    "A Fundraiser",
      account_title:            "Fifty and Fifty",
      permalink:                "a-fundraiser",
      description:              "",
      goal_in_cents:            10000,
      goal:                     100,
      goal_formatted:           "$100.00",
      amount_raised_in_cents:   1000,
      amount_raised:            10,
      amount_raised_formatted:  "$10.00",
      campaign_id:              1,
      person_id:                1,
      public_url:               {URL},
      iframe_url:               {URL},
      photo {
        original:     {URL},
        medium:       {URL},
        average:      {URL},
        small:        {URL},
        thumb:        {URL},
        icon:         {URL}
      }
    },
    {...},
    {...}
  ]
}