They are answered by the XTRF community and our experts


Customer API forbidden characters

Dennis Rosenbaum 4 years ago in API updated by Mateusz Trzeciak (XTRF Deployment & Training Specialist) 4 years ago 1

I received an error message from XTRF while trying to add a customer through the XTRF API (POST /customers).

The error messages states: Field contains one or more of forbidden characters.

I found out that the company name may not contain a '>' character. Though I couldn't find any documentation of other forbidden characters. Can someone provide me a list of these forbidden characters?


Create receivables for "classic project" via API

milos 5 years ago in API 0


it seems that there is no way of creating new receivables via API for the CLASSIC project? Or Im missing something in your documentation


Cannot remove a CAT receivable through the API

Dennis Rosenbaum 5 years ago in API 0


I'm trying to remove all the receivables through the API.
This is the process that I use:

  1. Retrieve the Receivable ID's through a Macro (for my quote, it shows '461')
    #set($receivableIds = $utils.createNewArrayList())
    #foreach($quote in $list)#*
        *##foreach($task in $quote.tasks)#*
            *##foreach($receivable in $quote.getTaskFinance($task).getAllReceivables())#*
            *##set($temp = $receivableIds.add($*
    #foreach($receivableId in $receivableIds)$receivableId,#end
  2. Verify this result by checking the quote itself:
    onmouseover=", true, false);"
  3. Execute the API call
    DELETE /api/v2/quotes/4YTI6WVKGRE2ZLXJ5KG3GGAJ24/finance/receivables/461 HTTP/1.1
  4. This fails with this message:
    {"status":400,"errorMessage":"No receivable with id: 461 for quote with id: 4759","detailedMessage":null}

When I add a regular receivable, it does work. Only with the CAT receivables it doesn't work.

Is it possible to be fixed? Or am I doing something wrong?

Kind regards,
Dennis Rosenbaum


Notify through API when a quote is deleted

Dennis Rosenbaum 5 years ago in API updated 5 years ago 2

I would like to have the possibility to know when quotes are deleted. There should be a 'quote_deleted' subscription available. 

The reason is that we use a secondary system and sync this with the XTRF state. When a quote is deleted in XTRF, it should also be deleted in the secondary system.

Or is there maybe another way to achieve this?

Under review

XTRF Summit - Smart Connectivity presentation

Bartosz Gumuła (XTRF Solution Architect) 5 years ago in API updated by mark 4 years ago 7


During the XTRF Summit, I was designated as a person that will showcase some of the XTRF connectivity with third-party tools, one of those is Google Data Studio (basically, better-looking reports).

I could try to use my experience to do so but I figured that maybe you have an idea for a few reports that would benefit from graphic display instead of just pure numbers. I would prefer to do it from PM point of view instead of management but I am open for suggestion. 

Best regards,


Is it possible to update client invoice payment dat via API?

Robrecht Belien 6 years ago in API updated by Michal 5 years ago 4

Hi I can't find any function in the API docs to add client invoice payments. But Xtrf and Quickbooks have an integration so it should be possible via code. Having this functionality would be great for us.


XTRF 8 allows for parametrized macros via API. That is the only known way to add clients payments.

The integration with QuickBooks is a hard-coded one that bypasses the API.


How to get job id of existing job in XTRF smart project

WK Automotive 6 years ago in API updated by Łukasz Kaleta (Senior Customer Success Manager) 6 years ago 5

I would like to update the status of existing jobs in XTRF smart projects using the XTRF Home Portal API.

The API call requires a job ID, but I don't where to find this ID.

End point: .../v2/jobs/{jobId}/status

Following the solution of a similar question on stackoverflow, I have defined a view with a list of jobs that require updating. However, there seems to be no column that holds the {jobId} that is required for the API. There is a column called "Internal ID" that contains a 4-digit number (in my case). But when I use that number in the API call, there's an error:

"Invalid Job ID of a Smart Job. Use new form of Job ID for Smart Jobs (e.g. 2QROVSCO3ZG3NM6KAZZBXH5HMI)."

So apparently, there is a new form for the job ID. Is there a specific column for the view that I should use, or is there another way to retrieve this job ID?


Subscription API - callback

Eric Kruis 6 years ago in API updated by Łukasz Kaleta (Senior Customer Success Manager) 6 years ago 6

We are implementing the Subscription API. From documentation we see that "Subscriptions are automatically removed if they do not work".

I can imagine that our custom application we are developing will not always available (ie planned maintenance, lost internet connection).

How can we see which subscription status changes are missed? Is there a log table in XTRF? Or is there a queue, where we can 'refire' the missed call from XTRF?


Issues with API since the upgrade

Michal Shinitzky 6 years ago in API 0


This question is for all those API developers:

Since the upgrade some function in our API code aren't working as they were:

1. Attach a file to a project/quote request.

2. New potential client - when we create a new potential client and then send the quote, we get a 403 error. Any idea why is this happening?

thank you in advance!


Searching answer

BIRT Eclipse report templates: how to add EU VAT number

Stan 6 years ago in API updated by Thierry ABAQUE 5 years ago 6


The dynamic fields corresponding to EU VAT disappeared in the new XTRF templates. While I can see a field with our company EU VAT –

(xtrfContext.getRootObject().getCustomer().getBranch().getCountrySpecificFiscalCodeValue() != "" ? reportContext.getMessage("pdf.eu_vat", reportContext.getLocale()) + " " + xtrfContext.getRootObject().getCustomer().getBranch().getCountrySpecificFiscalCodeValue() : "")

 – I would like to know there the XTRF BIRT expressions are stored. XTRF Knowledge base here at UserEcho seems not to cover this important issue.