Create a new project in the 1159 Finance system.

Example URI

POST /api/v1/projects

Excample request body show

{
  "name": "Sample Project 3",
  "description": "Debtors outside of germany",
  "default": false
}

Valid JSON Parametersshow

• namestring

  Name for the new project.

• descriptionstring (optional)

  Description for the new project.

• defaultboolean (optional)

  If set to true this new project will be set as your default project.

• client_idint (optional)

  If set, the project is added to a subclient instead of the main client.

Response on success

HTTP-Code 201

Headers

Content-Type: application/json

Body

{
  "error": false,
  "project_id": 54
}

Response on errorshow

• MISSING_NAME

  You did not provide a name for the project.

• INVALID_NAME

  The name you provided for the project is invalid.

• PROJECT_NAME_EXISTS

  A project with this name is already present in your account. You cannot have two projects with the same name.

• CREATE_FAILED

  The project could not be created.

• UNKNOWN_CLIENT

  The client provided for the project was not found in the system.

Create a new client in the 1159 Finance system.

Example URI

POST /api/v1/clients

Excample request body show

{
  "name": "Sample Client 3",
  "street": "Address of company 123",
  "postcode": "12345",
  "city": "Location name",
  "country": "at",
  "default": false
}

Valid JSON Parametersshow

• namestring

  Name for the new client.

• streetstring

  Street address of the new client.

• postcodestring

  Postal code of the address.

• citystring

  City of the address.

• countrystring

  ISO two-letter code of the client's country.

Response on success

HTTP-Code 201

Headers

Content-Type: application/json

Body

{
  "error": false,
  "client_id": 54
}

Response on errorshow

• MISSING_NAME

  You did not provide a name for the client.

• INVALID_NAME

  The name you provided for the client is invalid.

• CLIENT_NAME_EXISTS

  A client with this name is already present in your account. You cannot have two clients with the same name.

• INVALID_COUNTRY

  The country code you provided is not known to the system.

• INVALID_ADDRESS

  The address you provided could not be verified by the system.

• CREATE_FAILED

  The client could not be created.

Submit claims to the 1159 Finance system.

Example URI

POST /api/v1/cases

Excample request body show

{
  "literalVoucher": false,
  "debtors": [
    {
      "gender": "m",
      "title": "",
      "firstname": "John",
      "lastname": "Smith",
      "birth_name": "",
      "birthdate": "1964-10-22",
      "street": "Smith Lane 123",
      "street_add": "Apt. 23b",
      "postcode": "12345",
      "city": "Berlin",
      "country": "de",
      "phone": "+49123456789",
      "email": "johnsmith@mail.com"
      "customer_debtor_id": 99887766,
      "project": "myProject",
      "claims": [
        {
          "amount": 122.55,
          "date": "2015-09-21",
          "voucher": "INV-12345",
          "description": "Monthly Fee July 2017 for Service X",
          "currency": "EUR",
          "subclaim": false,
          "contract_ip": "124.123.122.12",
          "contract_subject": "99.00",
          "contract_time": "2014-02-15",
          "domain": "myservice.de",
          "username": "myusernameiscool",
          "freetext_1": "some information",
          "freetext_2": "2016-07-10",
          "freetext_3": "",
          "freetext_4": "",
          "freetext_5": "",
          "freetext_6": "",
          "freetext_7": "",
          "freetext_8": "",
          "freetext_9": "",
          "freetext_10": ""
        },
        {
          "amount": 5.0,
          "date": "2015-11-12",
          "voucher": "INV-12345",
          "description": "dunning fee",
          "currency": "EUR",
          "subclaim": true
        }
      ]
    }  
  ]
}

Valid JSON Parametersshow

• literalVoucherboolean (optional)

  If set to true the claim vouchers are compared as is. If false (default) INV-1234 will be treated the same as inv1234 when searching for duplicates.

• debtorsarray

  List of debtor objects to submit.

• genderstring ['m', 'f', 'male', 'female']

  Gender of the debtor.

• titlestring (optional)

  Title of the debtor, e. g. 'Dr.'

• firstnamestring

  First name of the case to update.

• lastnamestring

  Last name of the case to update.

• birth_namestring (optional)

  Maiden name of the debtor.

• birthdatestring [YYYY-MM-DD] (optional)

  Birth date of the debtor.

• streetstring

  Street and house number of home address.

• street_addstring (optional)

  Additional address information, e. g. c/o address.

• postcodestring

  Postal code of home address.

• citystring

  City matching the postal code and street.

• countrystring

  Two letter ISO code of the country.

• phonestring (optional)

  Phone number (mobile or wired), preferable in international form.

• emailstring (optional)

  Email address.

• customer_debtor_idint (optional)

  Your internal unique id for this debtor. You can search for this later to find your debtors in the 1159 Finance system.

• projectstring (optional)

  The project that your submitted claims should be assigned to. If provided this project has to be created in the 1159 Finance system previously. If ommitted the default project of your account will be used.

• claimsarray

  The actual list of claims to submit for this debtor.

• amountdouble

  The claim amount of this claim. Decimal sign is a dot, valid values are e.g. 12.50 or 12.5 or 23.

• datestring [YYYY-MM-DD]

  The claim date of this claim. It is used to calculate interest, for example.

• voucherstring

  The voucher for this claim. It has to be unique for all your debtors. If you mark this claim as 'subclaim: true' you have to provide the same voucher as you did for the related main claim.

• descriptionstring (optional)

  The description that will be shown on the dunning letters sent to the debtor. If you ommit this there will be a default description, e. g. 'Invoice {voucher} from {claim_date}'. If you provide a description you have to insert date and voucher yourself if needed, as it is not added to custom descriptions.

• currencystring ['EUR', 'CHF']

  The currency of this claim. You cannot mix currencies in the same project.

• subclaimboolean (optional)

  If set to true this claim will be marked as subclaim, e. g. for dunning fee or chargeback cost.

• contract_timestring [YYYY-MM-DD]

  The date on which the contract on which the claim is based was concluded.

• contract_subjectstring [XX.YY]

  The 1159 Finance catalog number for the subject of your contract. E. g. for web hosting this is 05.01. Please consult your contact person if you do not know the appropriate catalog number for your claims.

• contract_ipstring (optional)

  This is the ip address of your customer at the time of registration.

• domainstring (optional)

  This is the portal domain your customer has registered on.

• usernamestring (optional)

  This is the username your customer used on registration.

• freetext_Xstring (optional)

  You can provide up to 20 freetext fields for your claims. These can contain further information, e. g. shipping id etc.
  Please always put the same information type into the fields for your claims to avoid confusion.

Response on success show

HTTP-Code 201

Content-Type: application/json

{
  "error": false,
  "warnings": 1,
  "errors": 0,
  "debtors": [
    {
      "insert_status": {
        "inserted": true,
        "result": "WARNING",
        "debtor_id": 54321,
        "case_id": 145443
      },
      "gender": "m",
      "title": "",
      "firstname": "John",
      "lastname": "Smith",
      "birth_name": "",
      "birthdate": "1964-10-22",
      "street": "Smith Lane 123",
      "street_add": "Apt. 23b",
      "postcode": "12345",
      "city": "Berlin",
      "country": "de",
      "phone": "+49123456789",
      "email": "johnsmith@mail.com"
      "customer_debtor_id": 99887766,
      "project": "myProject",
      "claims": [
        {
          "amount": 122.55,
          "date": "2015-09-21",
          "voucher": "INV-12345",
          "description": "Monthly Fee July 2017 for Service X",
          "currency": "EUR",
          "subclaim": false,
          "contract_ip": "124.123.122.12",
          "contract_subject": "99.00",
          "contract_time": "2014-02-15",
          "domain": "myservice.de",
          "username": "myusernameiscool",
          "freetext_1": "some information",
          "freetext_2": "2016-07-10",
          "freetext_3": "",
          "freetext_4": "",
          "freetext_5": "",
          "freetext_6": "",
          "freetext_7": "",
          "freetext_8": "",
          "freetext_9": "",
          "freetext_10": ""
        },
        {
          "amount": 5.0,
          "date": "2015-11-12",
          "voucher": "INV-12345",
          "description": "dunning fee",
          "currency": "EUR",
          "subclaim": true
        }
      ]
    }  
  ]
}

Response on errorshow

• MISSING_DEBTORS

  You did not provide a 'debtors' array in your JSON request.

• INVALID_DEBTOR_DATA

  You provided invalid data in a debtor's attribute. See 'information' attribute for details.

• MISSING_CLAIMS

  You did not provide a 'claims' array for all submitted debtors.

• INVALID_CLAIM_DATA

  You provided invalid claim data. See 'information' attribute for details.

• DEBTOR_NOT_ALLOWED

  This debtor has been locked for further submissions. If you need details about this, please contact your sales manager.

• MISSING_SUBCLAIM_DESC

  Claims marked as 'subclaim': true must have a description (e. g. 'chargeback fee').

• SUBCLAIM_MISSING_CLAIM

  Each claim marked as 'subclaim': true must have the same voucher as the corresponding main claim.

• INVALID_VOUCHER

  You used an invalid voucher for your claim. Mostly this is because you tried to submit a claim twice.

• LOW_CASE_AMOUNT

  This error indicates that you sent a claim (sum of all claims sent in one request) that is below the defined limit for your account. Please contact your sales manager for details.

Submit a new file to the case with id {case_id}.

Example URI

POST /api/v1/cases/54321/files?filename=invoice.pdf&comment=Invoice

Valid Parameters

• case_idint

  The Id of the case you want to add claims to.

• filenamestring

  The filename of the PDF you want to upload.

• commentstring [0 - 255] (optional)

  A comment to assign to the uploaded file.

Request body

raw file contents

Response on success show

HTTP-Code 201

Content-Type: application/json

{
  "error": false,
  "case_id": 54321,
  "file_id": 65,
  "filename": "invoice.pdf",
  "filesize": 541992,
  "comment": "Invoice for Smith"
}

Response on errorshow

• MISSING_CASE_ID

  You did not provide a case id to upload the file into.

• CASE_NOT_FOUND

  The case id you provided was not found.

• UPLOAD_FAILED

  The upload failed (the server did not receive a valid file).

• FILE_SIZE_TOO_BIG

  The file's size exceeds the set limit.

• MISSING_FILE_NAME

  You did not provide a file name.

• INVALID_FILE_NAME

  Your file name contains invalid characters, e. g. slashes and double dots are not allowed.

• FILE_IS_NO_PDF

  Your uploaded file is no PDF. We can only accept PDF files for upload.

Submit a payment to the 1159 Finance system.

Example URI

POST /api/v1/payments

Excample request body show

{
  "debtor": {
    "firstname": "John",
    "lastname": "Smith",
    "customer_debtor_id": 9419419
  },
  "case_id": 54321,
  "case_name": "YU/SM-00054321-01",
  "voucher": "INV-1234",
  "payment": {
    "amount": 25.9,
    "date": "2017-10-30"
  }
}

Valid JSON Parametersshow

• debtorobject (optional)

  If you need to search by one or more debtor attributes instead of customer_debtor_id or voucher you can use the debtor object.

• firstnamestring (optional)

  Search debtor by first name.

• lastnamestring (optional)

  Search debtor by last name.

• customer_debtor_idstring (optional)

  Search debtor by your internal unique debtor id.

• case_idint (optional)

  Case's id to book the payment to.

• case_namestring (optional)

  Case's name to book the payment to.

• voucherstring (optional)

  The voucher that was paid (mostly your invoice number).

• paymentobject

  The actual payment that was made.

• amountdouble

  The payment amount that was made.

• amountstring [YYYY-MM-DD] (optional)

  The date of the payment. If ommitted the current date is used.

Response on success show

HTTP-Code 201

Content-Type: application/json

{
  "error": false,
  "payment": {
    "amount": 25.9,
    "date": "2017-10-30"
  },
  "case": {
    "case_id": 54321,
    "case_name": "YU/SM-00054321-01",
    "remaining": 48.2
  }
}

Response on errorshow

• MISSING_DEBTOR_OR_CASE_DATA

  You did not provided any criteria to select the case you want to add a payment to.

• INVALID_PAYMENT_DATE

  The payment date is invalid. Please use YYYY-MM-DD form.

• MISSING_PAYMENT_AMOUNT

  You did not provide a payment amount.

• INVALID_PAYMENT_AMOUNT

  The payment amount you provided is invalid.

• NO_CASE_FOUND

  We could not find any case for the criteria you provided.

• MULTIPLE_CASES_FOUND

  We found more than one case for the criteria you provided.

• ERROR_PROCESSING_PAYMENT

  The payment could not be processed. Please see 'information' attribute for details.

Submit an address to the address checking API.
Important: The address check currently only supports german addresses to the full amount. Other countries might give no or incomplete results.

Example URI

POST /api/v1/addresscheck

Excample request body show

{
  "gender": "f",
  "firstname": "John",
  "lastname": "Smith",
  "street": "Hauptstr. 12",
  "postcode": "12345",
  "city": "Berlin",
  "country": "de",
  "email": "asdf1234@yahoo.com"
}

Valid JSON Parametersshow

• genderstring ['m', 'f'] (optional)

  Gender to check.

• firstnamestring (optional)

  First name to check.

• lastnamestring (optional)

  Last name to check.

• streetstring (optional)

  Street to check.

• postcodestring (optional)

  Postal code to check.

• citystring (optional)

  City to check.

• countrystring (optional)

  Country to check - two letter ISO code, e. g. 'de', 'gb' etc. Defaults to 'de'.

• emailstring (optional)

  Email address to check.

Response on successshow

HTTP-Code 200

Content-Type: application/json

{
  "error": false,
  "gender": {
    "value": "f",
    "passed": false,
    "error": "WRONG_GENDER",
    "proposal": "m"
  },
  "firstname": {
    "value": "John",
    "passed": true
  },
  "lastname": {
    "value": "Smith",
    "passed": true
  },
  "street": {
    "value": "Hauptstra\u00dfe 12",
    "passed": true
  },
  "postcode": {
    "value": "12345",
    "passed": true
  },
  "city": {
    "value": "Berlin",
    "passed": true
  },
  "email": {
    "value": "asdf1234@yahoo.com",
    "passed": false,
    "error": "POSSIBLY_INVALID",
    "proposal": "",
    "score": 25
   },
   "known": false,
   "outdated": false
}

Response error codesshow

Unlike the other API endpoints, the addresscheck does not return an error code in the global 'error' attribute. Instead, each checked address field gets a passed attribute that is set to false if the check failed. In this case an additional error attribute is returned that contains one of the codes below.

• INVALID (email)

  Indicates that an email address is invalid, either as it is known to not exist or being fake or formal incorrect.

• POSSIBLY_INVALID (email)

  Indicates that an email address might be invalid or fake.

• SWITCHED (firstname, lastname)

  Indicates that you might have switched first and last name in your request.

• WRONG_GENDER (gender)

  The gender that you submitted does not match the first name.

• POSSIBLY_WRONG_GENDER (gender)

  The gender that you submitted might not match the first name. You should double-check it.

• UNKNOWN_NAME (firstname)

  The first name that you submitted is not known to our database.

• UNKNOWN_NAME_PART (firstname)

  You submitted multiple first names and at least one of them is not known to our database.

• UNCHECKED (street)

  The street you submitted was not checked as the postal code and zip did not match or were not provided.

• UNKNOWN_STREET (street)

  The street you submitted is not known or does not match the postal code and/or city.

• UNKNOWN_ADDRESS (postcode, city)

  The address seems to be incorrect. We could not match postal code, city and street.

• UNKNOWN_ADDRESS_05 (postcode, city)

  The address might be incorrect or contain some typos. You should double-check it.

• UNKNOWN_ADDRESS_01 (postcode, city)

  The address might contain small typos. You should double-check it.

• UNKNOWN_POSTCODE (postcode)

  The postal code was not found in our database.

• UNKNOWN_CITY (city)

  The city was not found in our database.